diff --git a/apps/docs/src/components/app/AppNav.vue b/apps/docs/src/components/app/AppNav.vue index 2627a018..87bcea42 100644 --- a/apps/docs/src/components/app/AppNav.vue +++ b/apps/docs/src/components/app/AppNav.vue @@ -40,14 +40,25 @@ name: 'Foundation', children: [ { name: 'createContext', to: '/composables/foundation/create-context' }, - { name: 'createTrinity', to: '/composables/foundation/create-trinity' }, { name: 'createPlugin', to: '/composables/foundation/create-plugin' }, + { name: 'createTrinity', to: '/composables/foundation/create-trinity' }, + ], + }, + { + name: 'Plugins', + children: [ + { name: 'useBreakpoints', to: '/composables/plugin/use-breakpoints' }, + { name: 'useHydration', to: '/composables/plugin/use-hydration' }, + { name: 'useLocale', to: '/composables/plugin/use-locale' }, + { name: 'useStorage', to: '/composables/plugin/use-storage' }, + { name: 'useTheme', to: '/composables/plugin/use-theme' }, ], }, { name: 'Registration', children: [ { name: 'useRegistry', to: '/composables/registration/use-registry' }, + { name: 'useProxyModel', to: '/composables/registration/use-proxy-model' }, { name: 'useTokens', to: '/composables/registration/use-tokens' }, ], }, @@ -56,32 +67,20 @@ children: [ { name: 'useFilter', to: '/composables/selection/use-filter' }, { name: 'useGroup', to: '/composables/selection/use-group' }, + { name: 'useSelection', to: '/composables/selection/use-selection' }, { name: 'useSingle', to: '/composables/selection/use-single' }, { name: 'useStep', to: '/composables/selection/use-step' }, ], }, - { - name: 'Forms', - children: [ - ], - }, { name: 'System', children: [ { name: 'useKeydown', to: '/composables/system/use-keydown' }, + { name: 'useLayout', to: '/composables/system/use-layout' }, { name: 'useLogger', to: '/composables/system/use-logger' }, ], }, - { - name: 'Plugins', - children: [ - { name: 'useBreakpoints', to: '/composables/plugin/use-breakpoints' }, - { name: 'useHydration', to: '/composables/plugin/use-hydration' }, - { name: 'useLocale', to: '/composables/plugin/use-locale' }, - { name: 'useStorage', to: '/composables/plugin/use-storage' }, - { name: 'useTheme', to: '/composables/plugin/use-theme' }, - ], - }, + ], }, { divider: true }, diff --git a/apps/docs/src/pages/composables/foundation/create-plugin.md b/apps/docs/src/pages/composables/foundation/create-plugin.md index 96fbb7ba..9913c005 100644 --- a/apps/docs/src/pages/composables/foundation/create-plugin.md +++ b/apps/docs/src/pages/composables/foundation/create-plugin.md @@ -1,3 +1,102 @@ +--- +title: createPlugin +description: A universal plugin factory to reduce boilerplate code for Vue plugin creation. +keywords: createPlugin, plugin, Vue, factory +--- + # createPlugin -This composable is used to create a plugin for the framework. It allows you to define a plugin with specific functionality that can be registered and used within your application. +The `createPlugin` factory function is a universal plugin factory designed to reduce boilerplate code when creating Vue plugins. It provides a structured way to define plugin behavior, including providing context and setting up the application. + +## API + +### `PluginOptions` + +```ts +export interface PluginOptions { + namespace: string + provide: (app: App) => void + setup?: (app: App) => void +} +``` + +Defines the options for creating a plugin: +- `namespace`: A string that uniquely identifies the plugin. +- `provide`: A function that receives the Vue `App` instance and is used to provide values to the application's context. +- `setup?`: An optional function that receives the Vue `App` instance and is used for additional setup logic after context has been provided. + +### `createPlugin(options)` + +* **Type** + + ```ts + export function createPlugin (options: PluginOptions): Z + ``` + +* **Details** + + - `options`: A `PluginOptions` object that configures the plugin. + + Returns a Vue plugin object with an `install` method. When the plugin is installed with `app.use()`, the `provide` and `setup` functions defined in `options` are executed within the application's context. + +## Examples + +### Creating a Simple Plugin + +```ts +// plugins/my-simple-plugin.ts +import { createPlugin } from '@vuetify/v0/factories/createPlugin' +import { ref } from 'vue' + +export const myPlugin = createPlugin({ + namespace: 'my-simple-plugin', + provide: (app) => { + // Provide a global reactive counter + app.provide('myCounter', ref(0)) + }, + setup: (app) => { + // Optional setup logic, e.g., global mixins or directives + console.log('My Simple Plugin setup complete!') + }, +}) +``` + +### Using the Plugin in `main.ts` + +```ts +// main.ts +import { createApp } from 'vue' +import App from './App.vue' +import { myPlugin } from './plugins/my-simple-plugin' + +const app = createApp(App) + +app.use(myPlugin) + +app.mount('#app') +``` + +### Consuming the Provided Value in a Component + +```html + + + +``` + + diff --git a/apps/docs/src/pages/composables/index.md b/apps/docs/src/pages/composables/index.md index ee5cd872..e2e6c6d6 100644 --- a/apps/docs/src/pages/composables/index.md +++ b/apps/docs/src/pages/composables/index.md @@ -4,23 +4,46 @@ Reusable pieces of logic that can be shared across components, providing encapsu ## Available Composables +### Foundation + +| Name | Description | +| - | - | +| [createContext](/composables/foundation/create-context) | Create reusable context to share state across components | +| [createPlugin](/composables/foundation/create-plugin) | | +| [createTrinity](/composables/foundation/create-trinity) | Standardized context pattern utility | + +### Plugins + +| Name | Description | +| - | - | +| [useBreakpoints](/composables/plugin/use-breakpoints) | Responsive breakpoint detection for different screen sizes | +| [useHydration](/composables/plugin/use-hydration) | Manage SSR hydration process | +| [useLocale](/composables/plugin/use-locale) | Internationalization system for multiple languages | +| [useStorage](/composables/plugin/use-storage) | Reactive interface to browser storage APIs | +| [useTheme](/composables/plugin/use-theme) | Application theme management with CSS custom properties | + +### Registration + +| Name | Description | +| - | - | +| [useRegistry](/composables/registration/use-registry) | Foundation for registration-based systems | +| [useProxyModel](/composables/registration/use-proxy-model) | | +| [useTokens](/composables/registration/use-tokens) | Design token management system | + +### Selection + +| Name | Description | +| - | - | +| [useFilter](/composables/selection/use-filter) | Filter arrays based on search queries | +| [useGroup](/composables/selection/use-group) | Manage collections with selection capabilities | +| [useSelection](/composables/selection/use-selection) | | +| [useSingle](/composables/selection/use-single) | Simplified single-selection wrapper around useGroup | +| [useStep](/composables/selection/use-step) | Manage multi-step processes like forms or wizards | + +### System + | Name | Description | | - | - | -| [useBreakpoints](/composables/use-breakpoints) | Responsive breakpoint detection for different screen sizes | -| [createContext](/composables/use-context) | Create reusable context to share state across components | -| [useFilter](/composables/use-filter) | Filter arrays based on search queries | -| [useGroup](/composables/use-group) | Manage collections with selection capabilities | -| [useHydration](/composables/use-hydration) | Manage SSR hydration process | -| [useKeydown](/composables/use-keydown) | Handle keyboard events with automatic cleanup | -| [useLocale](/composables/use-locale) | Internationalization system for multiple languages | -| [useMarkdown](/composables/use-markdown) | Render Markdown content in Vue applications | -| [useRegistry](/composables/use-registry) | Foundation for registration-based systems | -| [useSingle](/composables/use-single) | Simplified single-selection wrapper around useGroup | -| [useStep](/composables/use-step) | Manage multi-step processes like forms or wizards | -| [useStorage](/composables/use-storage) | Reactive interface to browser storage APIs | -| [useTheme](/composables/use-theme) | Application theme management with CSS custom properties | -| [useTokens](/composables/use-tokens) | Design token management system | -| [useTrinity](/composables/use-trinity) | Standardized context pattern utility | -| [useSingleton](/composables/use-singleton) | Extended trinity pattern with model binding | -| [toReactive](/composables/to-reactive) | Convert refs to reactive objects -| [useStorage](/composables/use-storage) | Persistent storage utilities for browser storage APIs with reactive state management. | +| [useKeydown](/composables/system/use-keydown) | Handle keyboard events with automatic cleanup | +| [useLayout](/composables/system/use-layout) | | +| [useLogger](/composables/system/use-logger) | | diff --git a/apps/docs/src/pages/composables/plugin/use-breakpoints.md b/apps/docs/src/pages/composables/plugin/use-breakpoints.md index b16f9b87..e94087ce 100644 --- a/apps/docs/src/pages/composables/plugin/use-breakpoints.md +++ b/apps/docs/src/pages/composables/plugin/use-breakpoints.md @@ -1,3 +1,85 @@ +--- +meta: + title: useBreakpoints + description: Simple hook to access the breakpoints context. + keywords: useBreakpoints, breakpoints, composable, Vue, responsive +category: Plugin +performance: 0 +--- + # useBreakpoints -The `useBreakpoints` composable is a utility for managing responsive design breakpoints in Vue applications. It allows you to define custom breakpoints and provides reactive properties to check the current viewport size against these breakpoints. +The `useBreakpoints` composable provides a simple hook to access the breakpoints context, allowing you to retrieve information about the current viewport dimensions and active breakpoints. + +## API + +### `useBreakpoints()` + +* **Type** + + ```ts + function useBreakpoints (): BreakpointsContext + ``` + +* **Details** + + Returns the breakpoints context containing current breakpoint information, such as `name`, `width`, `height`, `isMobile`, and boolean flags for each breakpoint (`xs`, `sm`, `md`, `lg`, `xl`, `xxl`, `smAndUp`, etc.). + +### `createBreakpointsPlugin(options?: BreakpointsOptions)` + +* **Type** + + ```ts + function createBreakpointsPlugin (options?: BreakpointsOptions): BreakpointsPlugin + ``` + +* **Details** + + Creates a Vue plugin for managing responsive breakpoints with automatic updates. This plugin sets up breakpoint tracking and updates the context when the window is resized, providing reactive breakpoint state throughout the application. The `options` parameter allows for custom configuration of breakpoint thresholds and mobile breakpoint. + +## Examples + +### Using `useBreakpoints` + +```html + + + +``` + +### Using `createBreakpointsPlugin` + +```ts +// main.ts +import { createApp } from 'vue' +import App from './App.vue' +import { createBreakpointsPlugin } from '@vuetify/v0/composables/useBreakpoints' + +const app = createApp(App) + +app.use(createBreakpointsPlugin({ + mobileBreakpoint: 'sm', + breakpoints: { + xs: 0, + sm: 320, + md: 768, + lg: 1024, + xl: 1280, + }, +})) + +app.mount('#app') +``` + + diff --git a/apps/docs/src/pages/composables/plugin/use-hydration.md b/apps/docs/src/pages/composables/plugin/use-hydration.md index 457a8b53..9453d257 100644 --- a/apps/docs/src/pages/composables/plugin/use-hydration.md +++ b/apps/docs/src/pages/composables/plugin/use-hydration.md @@ -1,3 +1,90 @@ +--- +meta: + title: useHydration + description: Simple hook to access the hydration context. + keywords: useHydration, hydration, composable, Vue, SSR, SSG +category: Plugin +performance: 0 +--- + # useHydration -A composable for managing the hydration process in SSR applications, controlling when and how components are hydrated to optimize performance and prevent hydration mismatches. +The `useHydration` composable provides a simple hook to access the hydration context, which is crucial for tracking client-side hydration state in Server-Side Rendered (SSR) or Static Site Generated (SSG) applications. + +## API + +### `useHydration()` + +* **Type** + + ```ts + function useHydration (): HydrationContext + ``` + +* **Details** + + Returns the hydration context containing `isHydrated` (a readonly shallow ref indicating if the application has been hydrated) and `hydrate` (a function to manually trigger hydration). + +### `createHydration()` + +* **Type** + + ```ts + function createHydration (): HydrationContext + ``` + +* **Details** + + Creates a hydration context for tracking client-side hydration state in SSR applications. This function provides a way to determine when the application has been fully hydrated on the client side, which is essential for SSR/SSG compatibility. + +### `createHydrationPlugin()` + +* **Type** + + ```ts + function createHydrationPlugin (): HydrationPlugin + ``` + +* **Details** + + Creates a Vue plugin for hydration state management in SSR/SSG applications. This plugin automatically detects when the root component is mounted and triggers the hydration process, ensuring proper client-side hydration timing. + +## Examples + +### Using `useHydration` + +```html + + + +``` + +### Using `createHydrationPlugin` + +```ts +// main.ts +import { createApp } from 'vue' +import App from './App.vue' +import { createHydrationPlugin } from '@vuetify/v0/composables/useHydration' + +const app = createApp(App) + +app.use(createHydrationPlugin()) + +app.mount('#app') +``` + + diff --git a/apps/docs/src/pages/composables/plugin/use-locale.md b/apps/docs/src/pages/composables/plugin/use-locale.md index dc9809ac..e32c89ab 100644 --- a/apps/docs/src/pages/composables/plugin/use-locale.md +++ b/apps/docs/src/pages/composables/plugin/use-locale.md @@ -1,3 +1,123 @@ +--- +meta: + title: useLocale + description: Simple hook to access the locale context. + keywords: useLocale, locale, i18n, internationalization, composable, Vue +category: Plugin +performance: 0 +--- + # useLocale -A composable for internationalization (i18n) - define and manage translations, switch between locales, and apply translations with variable replacement. +The `useLocale` composable provides a simple hook to access the locale context, which is used for managing internationalization with translations and number formatting. It supports message resolution with token references and locale-specific number formatting. + +## API + +### `useLocale()` + +* **Type** + + ```ts + function useLocale (): LocaleContext + ``` + +* **Details** + + Returns the locale context containing translation and formatting functions (`t` for translation, `n` for number formatting). + +### `createLocale(namespace?, options?)` + +* **Type** + + ```ts + export function createLocale< + Z extends LocaleTicket = LocaleTicket, + E extends LocaleContext = LocaleContext, + > ( + namespace?: string, + options?: LocaleOptions, + ): ContextTrinity + ``` + +* **Details** + + Creates a locale registry for managing internationalization. + - `namespace`: The namespace for the locale context (defaults to `v0:locale`). + - `options`: Configuration including `adapter` (for custom locale adapters), `default` (default locale ID), `fallback` (fallback locale ID), and `messages` (a record of locale messages). + + Returns an array containing the inject function, provide function, and the locale context. + +### `createLocalePlugin(options?)` + +* **Type** + + ```ts + export function createLocalePlugin< + Z extends LocaleTicket = LocaleTicket, + E extends LocaleContext = LocaleContext, + R extends TokenTicket = TokenTicket, + O extends TokenContext = TokenContext, + > (options?: LocalePluginOptions): LocalePlugin + ``` + +* **Details** + + Creates a Vue plugin for internationalization with locale management and translation support. Integrates with token system for message resolution and provides app-wide locale context. + - `options`: Configuration for `adapter`, `default` locale, `fallback` locale, and `messages`. + +## Examples + +### Using `useLocale` for Translation + +```html + + + +``` + +### Using `createLocalePlugin` + +```ts +// main.ts +import { createApp } from 'vue' +import App from './App.vue' +import { createLocalePlugin } from '@vuetify/v0/composables/useLocale' + +const app = createApp(App) + +app.use(createLocalePlugin({ + default: 'en', + messages: { + en: { + hello: 'Hello!', + welcome: 'Welcome, {0}!', + }, + es: { + hello: '¡Hola!', + welcome: '¡Bienvenido, {0}!', + }, + }, +})) + +app.mount('#app') +``` + + diff --git a/apps/docs/src/pages/composables/plugin/use-storage.md b/apps/docs/src/pages/composables/plugin/use-storage.md index 81fa1d26..c109fd4c 100644 --- a/apps/docs/src/pages/composables/plugin/use-storage.md +++ b/apps/docs/src/pages/composables/plugin/use-storage.md @@ -1,3 +1,142 @@ +--- +meta: + title: useStorage + description: Creates a reactive storage system with automatic persistence and cross-adapter support. + keywords: useStorage, storage, persistence, reactive, composable, Vue +category: Plugin +performance: 0 +--- + # useStorage -A reactive interface to browser storage APIs (`localStorage` and `sessionStorage`) with in-memory fallback, for synchronizing data between components and browser storage. +The `useStorage` composable creates a reactive storage system with automatic persistence and cross-adapter support. This function provides a consistent interface for storing and retrieving reactive values that automatically sync with the underlying storage adapter (e.g., `localStorage`, `sessionStorage`, or an in-memory adapter). + +## API + +### `StorageContext` + +```ts +export interface StorageContext { + get: (key: string, defaultValue?: T) => Ref + set: (key: string, value: T) => void + remove: (key: string) => void + clear: () => void +} +``` + +Defines the interface for the storage context: +- `get(key: string, defaultValue?: T)`: Retrieves a reactive `Ref` for the given `key`. If the key does not exist in storage, `defaultValue` is used. Changes to the `Ref` are automatically persisted. +- `set(key: string, value: T)`: Sets the value for the given `key` in storage. This will update the corresponding reactive `Ref`. +- `remove(key: string)`: Removes the item with the given `key` from storage. +- `clear()`: Clears all items from the storage. + +### `useStorage()` + +* **Type** + + ```ts + function useStorage (): StorageContext + ``` + +* **Details** + + A simple hook to access the storage context provided by `createStoragePlugin`. + +### `createStorage(options?)` + +* **Type** + + ```ts + export interface StorageOptions { + adapter?: StorageAdapter + prefix?: string + serializer?: { + read: (value: string) => any + write: (value: any) => string + } + } + + export function createStorage (options?: StorageOptions): E + ``` + +* **Details** + + Creates a reactive storage system. + - `adapter`: An optional `StorageAdapter` instance (defaults to `window.localStorage` in browser, or an in-memory adapter otherwise). + - `prefix`: An optional string prefix to prepend to all storage keys (defaults to `v0:`). + - `serializer`: An optional object with `read` and `write` functions for custom serialization/deserialization (defaults to `JSON.parse` and `JSON.stringify`). + + Returns a `StorageContext` object. + +### `createStoragePlugin(options?)` + +* **Type** + + ```ts + export interface StoragePlugin { + install: (app: App, ...options: any[]) => any + } + + export function createStoragePlugin (options?: StorageOptions): StoragePlugin + ``` + +* **Details** + + Creates a Vue plugin for reactive storage capabilities with automatic persistence. This plugin provides app-wide access to reactive storage that syncs with the configured adapter. The `options` parameter is the same as for `createStorage`. + +## Examples + +### Using `useStorage` in a Component + +```html + + + +``` + +### Using `createStoragePlugin` to Configure Global Storage + +```ts +// main.ts +import { createApp } from "vue"; +import App from "./App.vue"; +import { createStoragePlugin } from "@vuetify/v0/composables/useStorage"; + +const app = createApp(App); + +app.use( + createStoragePlugin({ + prefix: "my-app:", // Custom prefix for all keys + // adapter: sessionStorage, // Use sessionStorage instead of localStorage + }) +); + +app.mount("#app"); +``` + + diff --git a/apps/docs/src/pages/composables/plugin/use-theme.md b/apps/docs/src/pages/composables/plugin/use-theme.md index e7773531..a1cbbfbb 100644 --- a/apps/docs/src/pages/composables/plugin/use-theme.md +++ b/apps/docs/src/pages/composables/plugin/use-theme.md @@ -1,3 +1,196 @@ +--- +meta: + title: useTheme + description: Simple hook to access the theme context. + keywords: useTheme, theme, theming, composable, Vue +category: Plugin +performance: 0 +--- + # useTheme -A composable for theme management - register multiple themes, switch between them, and generate CSS custom properties. Requires the theme plugin to be installed. +The `useTheme` composable provides a simple hook to access the theme context, which is used for managing theme selections with dynamic color resolution. It supports token-based color systems and lazy theme loading for optimal performance. + +## API + +### `Colors` + +```ts +export type Colors = { + [key: string]: string +} +``` + +A type alias for an object where keys are color names and values are their string representations (e.g., hex codes, RGB). + +### `ThemeColors` + +```ts +export type ThemeColors = { + [key: string]: Colors | string +} +``` + +A type alias for an object representing a collection of theme colors, which can be nested `Colors` objects or direct color strings. + +### `ThemeTicket` + +```ts +export type ThemeTicket = SingleTicket & { + lazy: boolean +} +``` + +Extends `SingleTicket` with a `lazy` property, indicating if the theme should be loaded lazily. + +### `ThemeContext` + +```ts +export interface ThemeContext extends SingleContext { + colors: ComputedRef> + cycle: (themes: ID[]) => void + toggle: (themes: [ID, ID]) => void +} +``` + +Extends `SingleContext` with properties and methods for theme management: +- `colors`: A computed property containing the resolved colors for all themes, keyed by theme ID. +- `cycle(themes: ID[])`: Cycles through a list of theme IDs. If no themes are provided, it cycles through all registered themes. +- `toggle(themes: [ID, ID])`: Toggles between two specified theme IDs. + +### `ThemeOptions` and `ThemePluginOptions` + +```ts +export interface ThemeOptions extends ThemePluginOptions {} + +export interface ThemePluginOptions { + adapter?: ThemeAdapter + default?: ID + palette?: TokenCollection + themes?: Record +} +``` + +Configuration options for creating themes and the theme plugin: +- `adapter`: An optional `ThemeAdapter` instance for custom theme application (defaults to `Vuetify0ThemeAdapter`). +- `default`: The ID of the default theme to be selected. +- `palette`: A `TokenCollection` for global color tokens that can be referenced by themes. +- `themes`: A record where keys are theme IDs and values are `TokenCollection`s defining the colors for each theme. + +### `useTheme()` + +* **Type** + + ```ts + function useTheme (): ThemeContext + ``` + +* **Details** + + A simple hook to access the theme context provided by `createThemePlugin`. Returns the theme context containing current theme state and utilities. + +### `createTheme(namespace?, options?)` + +* **Type** + + ```ts + export function createTheme< + Z extends ThemeTicket = ThemeTicket, + E extends ThemeContext = ThemeContext, + > ( + namespace?: string, + options?: ThemeOptions, + ): ContextTrinity + ``` + +* **Details** + + Creates a theme registry for managing theme selections with dynamic color resolution. + - `namespace`: The namespace for the theme context (defaults to `v0:theme`). + - `options`: Configuration including `adapter`, `default` theme, `palette`, and `themes`. + + Returns a `ContextTrinity` containing the inject function, provide function, and the theme context. + +### `createThemePlugin(options?)` + +* **Type** + + ```ts + export interface ThemePlugin { + install: (app: App, ...options: any[]) => any + } + + export function createThemePlugin< + Z extends ThemeTicket = ThemeTicket, + E extends ThemeContext = ThemeContext, + R extends TokenTicket = TokenTicket, + O extends TokenContext = TokenContext, + > (options?: ThemePluginOptions): ThemePlugin + ``` + +* **Details** + + Creates a Vue plugin for theme management with automatic color system updates. Integrates with token system for dynamic color resolution and provides reactive theme switching capabilities throughout the application. The `options` parameter is the same as for `createTheme`. + +## Examples + +### Using `useTheme` in a Component + +```html + + + +``` + +### Using `createThemePlugin` to Configure Global Themes + +```ts +// main.ts +import { createApp } from "vue"; +import App from "./App.vue"; +import { createThemePlugin } from "@vuetify/v0/composables/useTheme"; + +const app = createApp(App); + +app.use( + createThemePlugin({ + default: "light", + palette: { + // Global palette colors + blue: "#2196F3", + red: "#F44336", + }, + themes: { + light: { + primary: "{blue}", + secondary: "#424242", + accent: "#82B1FF", + background: "#FFFFFF", + text: "#000000", + }, + dark: { + primary: "#BB86FC", + secondary: "#03DAC6", + accent: "#FF4081", + background: "#121212", + text: "#FFFFFF", + }, + }, + }) +); + +app.mount("#app"); +``` + + diff --git a/apps/docs/src/pages/composables/registration/use-proxy-model.md b/apps/docs/src/pages/composables/registration/use-proxy-model.md new file mode 100644 index 00000000..6ac2931f --- /dev/null +++ b/apps/docs/src/pages/composables/registration/use-proxy-model.md @@ -0,0 +1,137 @@ +--- +meta: + title: useProxyModel + description: Creates a proxy model for two-way binding with a selection context. + keywords: useProxyModel, proxy, model, two-way binding, selection, composable, Vue +category: Registration +performance: 0 +--- + +# useProxyModel + +The `useProxyModel` composable creates a proxy model for two-way binding with various selection contexts (e.g., `SelectionContext`, `GroupContext`, `SingleContext`, `StepContext`). It allows you to synchronize a local `ref` or `shallowRef` with the state of a selection registry, providing a convenient way to manage selected items. + +## API + +### `useProxyModel(registry, initial?, options?, _transformIn?, _transformOut?)` + +* **Type** + + ```ts + export interface ProxyModelOptions { + deep?: boolean + } + + export function useProxyModel ( + registry: SelectionContext, + initial?: Z | Z[], + options?: ProxyModelOptions, + _transformIn?: (val: Z[] | Z) => Z[], + _transformOut?: (val: Z[]) => Z | Z[], + ): ComputedRef + ``` + +* **Details** + + - `registry`: The selection context (e.g., from `useSelection`, `useGroup`, `useSingle`, `useStep`) that this proxy model will synchronize with. + - `initial?`: Optional initial value for the proxy model. Can be a single `SelectionTicket` or an array of `SelectionTicket`s. If provided, the proxy model will initialize the registry with these values. + - `options?`: Optional configuration object: + - `deep?: boolean`: If `true`, the internal model will use `ref` for deep reactivity; otherwise, it uses `shallowRef`. + - `_transformIn?`: An optional function to transform the incoming value from the model into the format expected by the registry (an array of `SelectionTicket`s). + - `_transformOut?`: An optional function to transform the outgoing value from the registry into the format expected by the model. + + Returns a `ComputedRef` that represents the two-way bound model. Changes to this computed ref will update the `registry`, and changes in the `registry` will update this computed ref. + +## Examples + +### Basic Usage + +```html + + + +``` + +### Using `useProxyModel` with `useSingle` + +```html + + + +``` + + diff --git a/apps/docs/src/pages/composables/registration/use-registry.md b/apps/docs/src/pages/composables/registration/use-registry.md index 3d0dec99..8263dba5 100644 --- a/apps/docs/src/pages/composables/registration/use-registry.md +++ b/apps/docs/src/pages/composables/registration/use-registry.md @@ -13,7 +13,7 @@ performance: 0 # useRegistry -A foundational composable for building registration-based systems, managing collections of registered items with automatic indexing, and lifecycle management. +The `useRegistry` composable creates a registry for managing collections of items with registration and lookup capabilities. This function provides the foundation for item management systems with ID-based, value-based, and index-based access patterns. ## API @@ -35,12 +35,14 @@ A foundational composable for building registration-based systems, managing coll has: (id: ID) => boolean browse: (value: unknown) => ID | ID[] | undefined lookup: (index: number) => ID | undefined + get: (id: ID) => Z | undefined find: (id: ID) => Z | undefined register: (item?: Partial) => Z unregister: (ids: ID | ID[]) => void reindex: () => void on: (event: string, cb: Function) => void off: (event: string, cb: Function) => void + emit: (event: string, data: any) => void } interface RegistryOptions { @@ -56,12 +58,14 @@ A foundational composable for building registration-based systems, managing coll - `has(id: ID)`: Returns `true` if an item with the given ID exists in the registry, `false` otherwise. - `browse(value: unknown)`: Returns the ID(s) associated with the given value. Returns a single ID if only one item has that value, an array of IDs if multiple items share the value, or `undefined` if not found. - `lookup(index: number)`: Returns the ID of the item at the given index, or `undefined` if not found. + - `get(id: ID)`: Retrieves the `RegistryTicket` object by its `id`. - `find(id: ID)`: Returns the registered item for the given ID, or `undefined` if not found. - `register(item?: Partial)`: Registers a new item. Returns the registered item; otherwise known as a **ticket**. - `unregister(ids: ID | ID[])`: Unregisters one or more items by their ID(s). Accepts either a single ID or an array of IDs for efficient batch removal. After processing all items, reindexes the remaining items. - `reindex()`: Rebuilds the index of items based on their current state. - `on(event: string, cb: Function)`: Listens for registry events (requires `events: true` option). - `off(event: string, cb: Function)`: Stops listening for registry events. + - `emit(event: string, data: any)`: Emits a custom event with associated data. - **Options** @@ -260,7 +264,7 @@ The catalog automatically handles duplicate values by: ### Batch Operations -For improved performance when removing multiple items, the `unregister` method accepts both single IDs and arrays of IDs. When multiple items are unregistered at once, the expensive reindexing operation is performed only once at the end, rather than after each individual removal. +For improved performance when removing multiple items, the `unregister` method accepts both single IDs and arrays of IDs. When multiple items are unregistered at once, the expensive re-indexing operation is performed only once at the end, rather than after each individual removal. ### Benchmarks @@ -279,7 +283,7 @@ The following table shows performance metrics for various `useRegistry` operatio *Performance metrics based on benchmark tests with 1,000 items and will vary based on collection size.* -## Example +## Examples The following example demonstrates creating a registry for reusable icon svg paths with event handling: @@ -382,3 +386,86 @@ graph TD C --> F[Event Listeners] F --> |register events| G[Console Logs] " /> + +### Basic Usage + +```html + + + +``` + +### Looking up items + +```html + + + +``` diff --git a/apps/docs/src/pages/composables/registration/use-tokens.md b/apps/docs/src/pages/composables/registration/use-tokens.md index 36369ad9..c3e65ffb 100644 --- a/apps/docs/src/pages/composables/registration/use-tokens.md +++ b/apps/docs/src/pages/composables/registration/use-tokens.md @@ -1,6 +1,15 @@ +--- +meta: + title: useTokens + description: Creates a token registry for managing design token collections with alias resolution. + keywords: useTokens, tokens, design tokens, composable, Vue +category: Registration +performance: 0 +--- + # useTokens -A utility for managing design tokens with support for hierarchical collections, aliases, and token resolution across your application's design system. +The `useTokens` composable creates a token registry for managing design token collections with alias resolution. It provides functionalities to store, retrieve, and resolve design tokens, including support for token aliases and nested token structures. ## API @@ -34,6 +43,9 @@ A utility for managing design tokens with support for hierarchical collections, ``` * **Details** The `useTokens` function creates takes a TokenCollection and maps it to a [Registry](/composables/registration/use-registry). It exposes a resolve function that allows you to retrieve the value of a token by its name or alias. The function supports nested collections and aliases, allowing for a flexible design token system. + - `tokens`: An optional `TokenCollection` to initialize the registry with. + + Returns a `TokenContext` object. ### `createTokensContext` @@ -46,3 +58,169 @@ A utility for managing design tokens with support for hierarchical collections, ``` * **Details** The `createTokensContext` function is a factory that creates a context for managing tokens. It takes a TokenCollection and returns a context object that includes the resolve function. This function is useful for creating a context that can be provided to components or composables that need access to the token system. + - `namespace`: The namespace for the token registry context. + - `tokens`: An optional `TokenCollection` to initialize the registry with. + + Returns a `TokenContext` object. + +### `flatten(tokens, prefix?)` + +* **Type** + + ```ts + function flatten (tokens: TokenCollection, prefix?: string): FlatTokenCollection[] + ``` + +* **Details** + + A utility function that flattens a nested `TokenCollection` into a flat array of `FlatTokenCollection` objects. Each flattened token includes its full ID (path) and its value. + - `tokens`: The `TokenCollection` to flatten. + - `prefix`: An optional string prefix to prepend to each token ID during flattening. + + +## Typescript + +### `TokenAlias` + +```ts +export interface TokenAlias { + [key: string]: any + $value: string + $type?: string + $description?: string +} +``` + +Represents a token alias, which is an object containing a `$value` property that references another token. It can also include optional `$type` and `$description` properties. + +### `TokenValue` + +```ts +export type TokenValue = string | number | boolean | TokenAlias +``` + +Defines the possible types for a token's value: a primitive (string, number, boolean) or a `TokenAlias` object. + +### `TokenCollection` + +```ts +export interface TokenCollection { + [key: string]: TokenValue | TokenCollection +} +``` + +Represents a collection of tokens, which can be a flat object or a deeply nested object structure where keys are token names and values are `TokenValue`s or other `TokenCollection`s. + +### `FlatTokenCollection` + +```ts +export type FlatTokenCollection = { + id: string + value: TokenValue +} +``` + +Represents a flattened token, containing its full `id` (path) and its `value`. + +### `TokenTicket` + +```ts +export interface TokenTicket extends RegistryTicket {} +``` + +Extends `RegistryTicket` and is used internally by the token registry. + +### `TokenContext` + +```ts +export interface TokenContext extends RegistryContext { + resolve: (token: string) => string | undefined +} +``` + +Extends `RegistryContext` with a `resolve` method: +- `resolve(token: string)`: Resolves a token string (which might be an alias like `{primary}`) to its final string value. Returns `undefined` if the token or its alias cannot be resolved. + +## Examples + +### Using `useTokens` to Resolve Design Tokens + +```html + + + +``` + +### Using `createTokensContext` with Vue's Provide/Inject + +```ts +// main.ts +import { createApp } from "vue"; +import App from "./App.vue"; +import { createTokensContext } from "@vuetify/v0/composables/useTokens"; + +const app = createApp(App); + +const designTokens = { + colors: { + brand: "#FF5722", + text: "#333333", + }, +}; + +const [, provideTokens, tokensContext] = createTokensContext("my-app-tokens", designTokens); + +app.use({ + install(app) { + provideTokens(tokensContext, app); + }, +}); + +app.mount("#app"); +``` + +```html + + + + +``` diff --git a/apps/docs/src/pages/composables/selection/use-filter.md b/apps/docs/src/pages/composables/selection/use-filter.md index 8d531759..2e9aa661 100644 --- a/apps/docs/src/pages/composables/selection/use-filter.md +++ b/apps/docs/src/pages/composables/selection/use-filter.md @@ -1,3 +1,122 @@ +--- +meta: + title: useFilter + description: Creates a reactive filter for arrays based on query matching with configurable search modes. + keywords: useFilter, filter, composable, Vue, data filtering +category: Selection +performance: 0 +--- + # useFilter -A composable for filtering arrays of items based on search queries, supporting both primitive values and complex objects with customizable filtering logic. +The `useFilter` composable creates a reactive filter for arrays based on query matching with configurable search modes. It supports 'some' (any field matches), 'every' (all fields match), 'union' (any query matches), and 'intersection' (all queries match) filtering strategies. + +## API + +### `useFilter(query, items, options?)` + +* **Type** + + ```ts + export function useFilter ( + query: FilterQuery, + items: MaybeRef, + options: UseFilterOptions = {}, + ): UseFilterResult + ``` + +* **Details** + + - `query`: The filter query to match against items. Can be a primitive value or an array of primitives. + - `items`: The collection of items to filter. Can be a `Ref` or a plain array. + - `options`: Optional configuration for the filter behavior: + - `customFilter?: FilterFunction`: A custom filter function to override the default behavior. + - `keys?: string[]`: An array of keys to search within each item (if items are objects). + - `mode?: FilterMode`: The filtering strategy to use: `'some'`, `'every'`, `'union'`, or `'intersection'`. Defaults to `'some'`. + + Returns an object with a `items` computed property, which is a computed reference to the filtered items based on the query and options. + +## Examples + +### Basic Usage + +```html + + + +``` + +### Using different filter modes + +```html + + + +``` + + diff --git a/apps/docs/src/pages/composables/selection/use-group.md b/apps/docs/src/pages/composables/selection/use-group.md index d819754d..42b5b9a3 100644 --- a/apps/docs/src/pages/composables/selection/use-group.md +++ b/apps/docs/src/pages/composables/selection/use-group.md @@ -1,3 +1,74 @@ +--- +meta: + title: useGroup + description: Creates a group selection context for managing collections of items where multiple selections can be made. + keywords: useGroup, group, selection, composable, Vue +category: Selection +performance: 0 +--- + # useGroup -The `useGroup` composable is designed to manage a group of related components, allowing for shared state and behavior across them. This is particularly useful in scenarios where you want to ensure that only one component in the group can be active at a time, such as in radio button groups or tabbed interfaces. +The `useGroup` composable creates a group selection context for managing collections of items where multiple selections can be made. This function extends the selection functionality provided by `useSelection` with group selection capabilities. + +## API + +### `useGroup(options?)` + +* **Type** + + ```ts + export function useGroup< + Z extends GroupTicket = GroupTicket, + E extends GroupContext = GroupContext, + > (options?: GroupOptions): E + ``` + +* **Details** + + - `options`: Optional configuration for group selection behavior. Extends `SelectionOptions` from `useSelection`. + + Returns a group selection context object (`GroupContext`) that includes properties and methods for managing group selections, such as `selectedIndexes` (a computed property containing a `Set` of selected item indexes) and `select` (a function to select items by their IDs). + +## Examples + +### Basic Usage + +```html + + + +``` + + diff --git a/apps/docs/src/pages/composables/selection/use-selection.md b/apps/docs/src/pages/composables/selection/use-selection.md new file mode 100644 index 00000000..5c5bc625 --- /dev/null +++ b/apps/docs/src/pages/composables/selection/use-selection.md @@ -0,0 +1,151 @@ +--- +meta: + title: useSelection + description: Creates a selection context for managing collections of selectable items. + keywords: useSelection, selection, composable, Vue, item management +category: Selection +performance: 0 +--- + +# useSelection + +The `useSelection` composable creates a selection context for managing collections of selectable items. This function extends the registry functionality provided by `useRegistry` with selection state management, allowing you to track which items are currently selected. + +## API + +### `SelectionTicket` + +```ts +export interface SelectionTicket extends RegistryTicket { + disabled: boolean + isActive: Readonly> + toggle: () => void +} +``` + +Extends `RegistryTicket` with properties for selection state: +- `disabled`: A boolean indicating if the item is disabled and cannot be selected. +- `isActive`: A readonly `Ref` indicating whether the item is currently selected. +- `toggle`: A function to toggle the selection state of the item. + +### `SelectionContext` + +```ts +export interface SelectionContext extends RegistryContext { + selectedIds: Reactive> + selectedItems: ComputedRef> + selectedValues: ComputedRef> + reset: () => void + select: (id: ID) => void + mandate: () => void +} +``` + +Extends `RegistryContext` with properties and methods for managing selections: +- `selectedIds`: A reactive `Set` containing the IDs of all currently selected items. +- `selectedItems`: A computed `Set` containing the full `SelectionTicket` objects of selected items. +- `selectedValues`: A computed `Set` containing the `value` properties of selected items. +- `reset()`: Clears all selected IDs and reindexes the registry. +- `select(id: ID)`: Toggles the selection state of the item with the given `id`. +- `mandate()`: Ensures that at least one item is selected if `mandatory` option is enabled. + +### `useSelection(options?)` + +* **Type** + + ```ts + export interface SelectionOptions extends RegistryOptions { + enroll?: boolean + mandatory?: boolean | 'force' + } + + export function useSelection< + Z extends SelectionTicket = SelectionTicket, + E extends SelectionContext = SelectionContext, + > (options?: SelectionOptions): E + ``` + +* **Details** + + - `options`: Optional configuration for selection behavior. Extends `RegistryOptions`. + - `enroll?: boolean`: If `true`, newly registered items are automatically selected if not disabled. Defaults to `false`. + - `mandatory?: boolean | 'force'`: If `true`, at least one item must always be selected. If `'force'`, it ensures the first item is selected if nothing else is. + + Returns a `SelectionContext` object with properties and methods for managing selections. + +## Examples + +### Basic Usage + +```html + + + +``` + +### Using `enroll` and `mandatory` options + +```html + + + +``` + + diff --git a/apps/docs/src/pages/composables/selection/use-single.md b/apps/docs/src/pages/composables/selection/use-single.md index 0e912576..4b4fd8c2 100644 --- a/apps/docs/src/pages/composables/selection/use-single.md +++ b/apps/docs/src/pages/composables/selection/use-single.md @@ -1,3 +1,12 @@ +--- +meta: + title: useSingle + description: Creates a single selection context for managing collections where only one item can be selected. + keywords: useSingle, single selection, composable, Vue, item management +category: Selection +performance: 0 +--- + @@ -6,9 +15,145 @@ A wrapper around `useGroup` that provides a simplified API for single-selection scenarios with singular selection properties and streamlined selection methods. +The `useSingle` composable creates a single selection context for managing collections where only one item can be selected at a time. This function extends the selection functionality provided by `useSelection` with single-selection constraints. + + + +## API + +### `SingleTicket` + +```ts +export interface SingleTicket extends SelectionTicket {} +``` + +Extends `SelectionTicket` and represents an item that can be part of a single selection. + +### `SingleContext` + +```ts +export interface SingleContext extends SelectionContext { + selectedId: ComputedRef + selectedIndex: ComputedRef + selectedItem: ComputedRef + selectedValue: ComputedRef +} +``` + +Extends `SelectionContext` with properties specific to single selection: +- `selectedId`: A computed property holding the ID of the currently selected item, or `undefined` if none is selected. +- `selectedIndex`: A computed property holding the index of the currently selected item, or `-1` if none is selected. +- `selectedItem`: A computed property holding the full `SingleTicket` object of the currently selected item, or `undefined`. +- `selectedValue`: A computed property holding the `value` of the currently selected item, or `undefined`. + +### `useSingle(options?)` + +* **Type** + + ```ts + export interface SingleOptions extends SelectionOptions {} + + export function useSingle< + Z extends SingleTicket = SingleTicket, + E extends SingleContext = SingleContext, + > (options?: SingleOptions): E + ``` + +* **Details** + + - `options`: Optional configuration for single selection behavior. Extends `SelectionOptions` from `useSelection`. + + Returns a `SingleContext` object with properties and methods for managing a single selection. When `select` is called, it ensures that only the specified item becomes selected, deselecting any previously selected item. + +## Examples + +### Basic Usage + +```html + + + +``` + +### Using `mandatory` option with `useSingle` + +```html + + + +``` + + diff --git a/apps/docs/src/pages/composables/selection/use-step.md b/apps/docs/src/pages/composables/selection/use-step.md index ecdee61c..ac9f5de4 100644 --- a/apps/docs/src/pages/composables/selection/use-step.md +++ b/apps/docs/src/pages/composables/selection/use-step.md @@ -1,3 +1,108 @@ +--- +meta: + title: useStep + description: Creates a step selection context for managing collections where users can navigate through items sequentially. + keywords: useStep, step, navigation, single selection, composable, Vue +category: Selection +performance: 0 +--- + # useStep -A composable for managing navigation through multi-step processes like forms, wizards, or onboarding flows, with support for step tracking, completion, and navigation controls. +The `useStep` composable creates a step selection context for managing collections where users can navigate through items sequentially. This function extends the single selection functionality provided by `useSingle` with stepping navigation, allowing for easy movement between items in a defined order. + +## API + +### `StepTicket` + +```ts +export interface StepTicket extends SingleTicket {} +``` + +Extends `SingleTicket` and represents an item that can be part of a step-by-step navigation. + +### `StepContext` + +```ts +export interface StepContext extends SingleContext { + first: () => void + last: () => void + next: () => void + prev: () => void + step: (count: number) => void +} +``` + +Extends `SingleContext` with methods for sequential navigation: +- `first()`: Selects the first item in the collection. +- `last()`: Selects the last item in the collection. +- `next()`: Selects the next item in the sequence. Wraps around to the beginning if at the end. +- `prev()`: Selects the previous item in the sequence. Wraps around to the end if at the beginning. +- `step(count: number)`: Advances or retreats the selection by a specified `count`. Positive `count` moves forward, negative moves backward. + +### `useStep(options?)` + +* **Type** + + ```ts + export interface StepOptions extends SingleOptions {} + + export function useStep< + Z extends StepTicket = StepTicket, + E extends StepContext = StepContext, + > (options?: StepOptions): E + ``` + +* **Details** + + - `options`: Optional configuration for step behavior. Extends `SingleOptions` from `useSingle`. + + Returns a `StepContext` object with properties and methods for managing sequential selection and navigation. + +## Examples + +### Basic Usage + +```html + + + +``` + + diff --git a/apps/docs/src/pages/composables/system/use-keydown.md b/apps/docs/src/pages/composables/system/use-keydown.md index 17a81ce9..e34e536e 100644 --- a/apps/docs/src/pages/composables/system/use-keydown.md +++ b/apps/docs/src/pages/composables/system/use-keydown.md @@ -1,6 +1,17 @@ +--- +meta: + title: useKeydown + description: Sets up global keyboard event listeners for specified key handlers with automatic cleanup. + keywords: useKeydown, keydown, keyboard, event listener, composable, Vue +category: System +performance: 0 +--- + # useKeydown -A composable for handling keyboard events with automatic cleanup, supporting multiple key combinations and customizable behavior. +The `useKeydown` composable sets up global keyboard event listeners for specified key handlers with automatic cleanup. This composable automatically starts listening when mounted and cleans up when the scope is disposed, providing a clean way to handle global keyboard interactions. + +## API ### `useKeydown(handlers)` @@ -28,6 +39,50 @@ Registers keyboard event handlers with automatic cleanup. | `preventDefault` | `boolean` | `false` | Whether to call `preventDefault()` on the event | | `stopPropagation` | `boolean` | `false` | Whether to call `stopPropagation()` on the event | +* **Type** + + ```ts + export interface KeyHandler { + key: string + handler: (event: KeyboardEvent) => void + preventDefault?: boolean + stopPropagation?: boolean + } + + export function useKeydown (handlers: KeyHandler[] | KeyHandler): { + startListening: () => void + stopListening: () => void + } + ``` + +* **Details** + + - `handlers`: A single `KeyHandler` object or an array of `KeyHandler` objects to register for keydown events. + - `key`: The `KeyboardEvent.key` value to listen for (e.g., `'Escape'`, `'Enter'`, `'ArrowUp'`). + - `handler`: The function to execute when the specified key is pressed. It receives the `KeyboardEvent` object. + - `preventDefault?`: Optional boolean. If `true`, `event.preventDefault()` will be called on the event. + - `stopPropagation?`: Optional boolean. If `true`, `event.stopPropagation()` will be called on the event. + + Returns an object with `startListening` and `stopListening` methods, allowing manual control over the event listeners. + +## Common Key Names + +| Key | Description | +|-----|-------------| +| `'Enter'` | Enter key | +| `'Escape'` | Escape key | +| `'Space'` | Space bar | +| `'ArrowUp'` | Up arrow | +| `'ArrowDown'` | Down arrow | +| `'ArrowLeft'` | Left arrow | +| `'ArrowRight'` | Right arrow | +| `'Tab'` | Tab key | +| `'Backspace'` | Backspace | +| `'Delete'` | Delete key | +| `'a'` - `'z'` | Letter keys | +| `'0'` - `'9'` | Number keys | +| `'F1'` - `'F12'` | Function keys | + ## TypeScript Support The composable is fully typed: @@ -51,20 +106,90 @@ const handlers: KeyHandler[] = [ const { startListening, stopListening } = useKeydown(handlers) ``` -## Common Key Names +## Examples + +### Handling a single key press + +```html + + + +``` + +### Handling multiple key presses + +```html + + + +``` + +### Manually starting and stopping listeners + +```html + + + +``` + -| Key | Description | -|-----|-------------| -| `'Enter'` | Enter key | -| `'Escape'` | Escape key | -| `'Space'` | Space bar | -| `'ArrowUp'` | Up arrow | -| `'ArrowDown'` | Down arrow | -| `'ArrowLeft'` | Left arrow | -| `'ArrowRight'` | Right arrow | -| `'Tab'` | Tab key | -| `'Backspace'` | Backspace | -| `'Delete'` | Delete key | -| `'a'` - `'z'` | Letter keys | -| `'0'` - `'9'` | Number keys | -| `'F1'` - `'F12'` | Function keys | diff --git a/apps/docs/src/pages/composables/system/use-layout.md b/apps/docs/src/pages/composables/system/use-layout.md new file mode 100644 index 00000000..1f79aca3 --- /dev/null +++ b/apps/docs/src/pages/composables/system/use-layout.md @@ -0,0 +1,180 @@ +--- +meta: + title: useLayout + description: Creates a layout context for managing the dimensions and positions of layout elements. + keywords: useLayout, layout, composable, Vue, dimensions, positioning +category: System +performance: 0 +--- + +# useLayout + +The `useLayout` composable creates a layout context for managing the dimensions and positions of layout elements within an application. It provides reactive properties for the overall window size, and calculated bounds for different layout sections (top, bottom, left, right), as well as the main content area. + +## API + +### `useLayout(options?)` + +* **Type** + + ```ts + export interface LayoutTicket extends GroupTicket { + order: number + position: LayoutLocation + value: number + } + + export interface LayoutContext extends GroupContext { + bounds: { + top: ComputedRef + bottom: ComputedRef + left: ComputedRef + right: ComputedRef + } + main: { + x: ComputedRef + y: ComputedRef + width: ComputedRef + height: ComputedRef + } + sizes: ShallowReactive> + height: ShallowRef + width: ShallowRef + } + + export interface LayoutOptions extends GroupOptions {} + + export function useLayout< + Z extends LayoutTicket = LayoutTicket, + E extends LayoutContext = LayoutContext, + > (_options: LayoutOptions = {}): E + ``` + +* **Details** + + - `_options`: Optional configuration for layout behavior. Extends `GroupOptions` from `useGroup`. + + Returns a layout context object (`LayoutContext`) that includes: + - `bounds`: Computed properties for the total `top`, `bottom`, `left`, and `right` occupied by registered layout elements. + - `main`: Computed properties for the `x`, `y`, `width`, and `height` of the main content area, excluding the space taken by layout elements. + - `sizes`: A `ShallowReactive` map storing the sizes of registered layout elements. + - `height`: A `ShallowRef` for the current window height. + - `width`: A `ShallowRef` for the current window width. + - `register`: A function to register new layout elements. + +## Examples + +### Basic Layout Usage + +```html + + + + + + + diff --git a/apps/docs/src/pages/composables/system/use-logger.md b/apps/docs/src/pages/composables/system/use-logger.md index 26f1bc13..e96078a5 100644 --- a/apps/docs/src/pages/composables/system/use-logger.md +++ b/apps/docs/src/pages/composables/system/use-logger.md @@ -1,3 +1,116 @@ +--- +meta: + title: useLogger + description: Provides a consistent logging interface with configurable adapters and levels. + keywords: useLogger, logger, logging, composable, Vue +category: System +performance: 0 +--- + # useLogger -This composable provides a simple logging utility that can be used throughout your application. It allows you to log messages with different severity levels (info, warn, error) and can be easily extended or modified to suit your needs. +The `useLogger` composable provides a consistent logging interface that can be configured with different adapters and optimized for production builds with conditional compilation. + +## API + +### `useLogger(namespace?)` + +* **Type** + + ```ts + function useLogger (namespace?: string): LoggerContext + ``` + +* **Details** + + A simple hook to access the logger context. If called within a component setup, it attempts to retrieve the provided logger context. If no context is found or if called outside a component setup, it returns a fallback logger. + +### `createLogger(options?)` + +* **Type** + + ```ts + export interface LoggerOptions { + adapter?: LoggerAdapter + level?: LogLevel + prefix?: string + enabled?: boolean + } + + export function createLogger (options?: LoggerOptions): LoggerContext + ``` + +* **Details** + + Creates a logger context for application logging with configurable adapters and levels. + - `adapter`: An optional `LoggerAdapter` instance (defaults to `Vuetify0LoggerAdapter`). + - `level`: The initial log level (e.g., `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `silent`). Defaults to `info`. + - `prefix`: An optional string prefix for log messages. + - `enabled`: An optional boolean to initially enable or disable the logger. + + Returns a `LoggerContext` object with methods like `debug`, `info`, `warn`, `error`, `trace`, `fatal`, `level`, `current`, `enabled`, `enable`, and `disable`. + +### `createLoggerPlugin(options?)` + +* **Type** + + ```ts + export interface LoggerPlugin { + install: (app: App, ...options: any[]) => any + } + + export function createLoggerPlugin (options?: LoggerOptions): LoggerPlugin + ``` + +* **Details** + + Creates a Vue plugin for logging. This plugin sets up the logger context and makes it available throughout the application. The `options` parameter is the same as for `createLogger`. + +## Examples + +### Using `useLogger` in a Component + +```html + + + +``` + +### Using `createLoggerPlugin` to Configure Global Logging + +```ts +// main.ts +import { createApp } from "vue"; +import App from "./App.vue"; +import { createLoggerPlugin, LogLevel } from "@vuetify/v0/composables/useLogger"; + +const app = createApp(App); + +app.use( + createLoggerPlugin({ + level: LogLevel.Debug, // Set global log level to debug + prefix: "MyApp", // Add a prefix to all log messages + }) +); + +app.mount("#app"); +``` + + diff --git a/apps/docs/src/typed-router.d.ts b/apps/docs/src/typed-router.d.ts index 5b3a8d96..c4a4c224 100644 --- a/apps/docs/src/typed-router.d.ts +++ b/apps/docs/src/typed-router.d.ts @@ -37,13 +37,16 @@ declare module 'vue-router/auto-routes' { '/composables/plugin/use-locale': RouteRecordInfo<'/composables/plugin/use-locale', '/composables/plugin/use-locale', Record, Record>, '/composables/plugin/use-storage': RouteRecordInfo<'/composables/plugin/use-storage', '/composables/plugin/use-storage', Record, Record>, '/composables/plugin/use-theme': RouteRecordInfo<'/composables/plugin/use-theme', '/composables/plugin/use-theme', Record, Record>, + '/composables/registration/use-proxy-model': RouteRecordInfo<'/composables/registration/use-proxy-model', '/composables/registration/use-proxy-model', Record, Record>, '/composables/registration/use-registry': RouteRecordInfo<'/composables/registration/use-registry', '/composables/registration/use-registry', Record, Record>, '/composables/registration/use-tokens': RouteRecordInfo<'/composables/registration/use-tokens', '/composables/registration/use-tokens', Record, Record>, '/composables/selection/use-filter': RouteRecordInfo<'/composables/selection/use-filter', '/composables/selection/use-filter', Record, Record>, '/composables/selection/use-group': RouteRecordInfo<'/composables/selection/use-group', '/composables/selection/use-group', Record, Record>, + '/composables/selection/use-selection': RouteRecordInfo<'/composables/selection/use-selection', '/composables/selection/use-selection', Record, Record>, '/composables/selection/use-single': RouteRecordInfo<'/composables/selection/use-single', '/composables/selection/use-single', Record, Record>, '/composables/selection/use-step': RouteRecordInfo<'/composables/selection/use-step', '/composables/selection/use-step', Record, Record>, '/composables/system/use-keydown': RouteRecordInfo<'/composables/system/use-keydown', '/composables/system/use-keydown', Record, Record>, + '/composables/system/use-layout': RouteRecordInfo<'/composables/system/use-layout', '/composables/system/use-layout', Record, Record>, '/composables/system/use-logger': RouteRecordInfo<'/composables/system/use-logger', '/composables/system/use-logger', Record, Record>, '/guide/accessibility': RouteRecordInfo<'/guide/accessibility', '/guide/accessibility', Record, Record>, '/guide/components': RouteRecordInfo<'/guide/components', '/guide/components', Record, Record>,