feat(useTokens): add token options for depth and prefix

Author: johnleider

apps/docs/src/pages/composables/registration/use-tokens.md

@@ -11,6 +11,7 @@ The `useTokens` composable allows you to define a collection of design tokens, w
 ```ts
 import { useTokens } from '@vuetify/v0'
 
+// Default behavior (depth = Infinity): fully flatten nested objects
 const tokens = useTokens({
   color: {
     primary: '#3b82f6',
@@ -26,6 +27,14 @@ const tokens = useTokens({
 tokens.resolve('color.primary') // '#3b82f6'
 tokens.resolve('color.info') // '#3b82f6' (alias resolved)
 tokens.resolve('radius.md') // '8px'
+
+const features = useTokens({
+  dark: true,
+  rtl: { value: true, variation: 'toggle' },
+}, { depth: 0 })
+
+// With depth: 0, nested objects are kept as-is at their base id
+features.resolve('rtl') // { value: true, variation: 'toggle' }
 ```
 
 ## API
@@ -57,10 +66,18 @@ tokens.resolve('radius.md') // '8px'
     resolve: (token: string | TokenAlias) => unknown | undefined
   }
 
+  interface TokenOptions {
+    depth?: number
+    prefix?: string
+  }
+
   function useTokens<
     Z extends TokenTicket = TokenTicket,
     E extends TokenContext<Z> = TokenContext<Z>,
-  > (tokens: TokenCollection): TokenContext<Z>
+  > (
+    tokens: TokenCollection,
+    options?: TokenOptions,
+  ): TokenContext<Z>
   ```
 
 * **Details**
@@ -69,13 +86,17 @@ tokens.resolve('radius.md') // '8px'
 * **Description**
   * Creates a token registry context initialized with an optional nested collection of tokens.
   * Flattens nested token collections into a flat list of token entries for registration.
+  * The `depth` option lets you control how deep flattening goes (default: Infinity). Set `depth: 0` to keep nested objects intact at their base id.
   * Supports tokens defined as primitive values or as aliases referencing other tokens.
   * Provides a resolve method to recursively resolve tokens and aliases into their final string value.
   * Utilizes caching for efficient resolution of repeated token lookups.
   * Integrates with a generic registry system (useRegistry) for management of tokens by ID.
 
 * **Parameters**
   * tokens (optional): A nested collection of tokens to initialize the registry.
+  * options (optional):
+    * depth?: number — how deep to flatten nested objects (default: Infinity)
+    * prefix?: string — a prefix to preprend to all generated ids
 
 * **Returns**
   * A token context object containing:

packages/0/src/composables/useTokens/index.test.ts

@@ -1,5 +1,5 @@
 // Composables
-import { createTokensContext } from './index'
+import { createTokensContext, useTokens } from './index'
 
 // Utilities
 import { describe, it, expect } from 'vitest'
@@ -73,6 +73,25 @@ describe('createTokensContext', () => {
       expect(context.resolve('colors.red.100')).toBe('#FEF2F2')
       expect(context.resolve('colors.red.200')).toBe('#FEF2F2')
     })
+
+    it('should respect depth option (depth=0 stops flattening)', () => {
+      const tokens: TokenCollection = {
+        dark: true,
+        rtl: { value: true, variation: 'toggle' },
+        complex: { inner: { leaf: '#FFFFFF' } },
+      }
+
+      const context = useTokens(tokens, { depth: 0 })
+
+      // With depth=0, nested objects remain as values at their base ids
+      expect(context.collection.size).toBe(3)
+      expect(context.collection.has('dark')).toBe(true)
+      expect(context.collection.has('rtl')).toBe(true)
+      expect(context.collection.has('complex')).toBe(true)
+
+      expect(context.resolve('rtl')).toEqual({ value: true, variation: 'toggle' })
+      expect(context.resolve('complex')).toEqual({ inner: { leaf: '#FFFFFF' } })
+    })
   })
 
   describe('alias resolution', () => {

packages/0/src/composables/useTokens/index.ts

@@ -42,6 +42,11 @@ export interface TokenContext<Z extends TokenTicket> extends RegistryContext<Z>
   resolve: (token: string | TokenAlias) => unknown | undefined
 }
 
+export interface TokenOptions {
+  depth?: number
+  prefix?: string
+}
+
 /**
  * Creates a token registry for managing design token collections with alias resolution.
  * Returns the token context directly for simple usage.
@@ -50,18 +55,23 @@ export interface TokenContext<Z extends TokenTicket> extends RegistryContext<Z>
  * @template Z The structure of the registry token items.
  * @template E The available methods for the token's context.
  * @returns The token context object.
+ *
+ * @see https://0.vuetifyjs.com/composables/registration/use-tokens
  * @see https://www.designtokens.org/tr/drafts/format/
  */
 export function useTokens<
   Z extends TokenTicket = TokenTicket,
   E extends TokenContext<Z> = TokenContext<Z>,
-> (tokens: TokenCollection = {}): E {
+> (
+  tokens: TokenCollection = {},
+  options: TokenOptions = {},
+): E {
   const logger = useLogger()
   const registry = useRegistry<Z, E>()
 
   const cache = new Map<string, unknown | undefined>()
 
-  registry.onboard(flatten(tokens) as Partial<Z>[])
+  registry.onboard(flatten(tokens, options.prefix, options.depth) as Partial<Z>[])
 
   function isAlias (token: unknown): token is string {
     return isString(token) && token.length > 2 && token[0] === '{' && token.at(-1) === '}'
@@ -185,12 +195,12 @@ export function createTokensContext<
  * @param prefix An optional prefix to prepend to each token ID.
  * @returns An array of flattened tokens, each with an ID and value.
  */
-function flatten (tokens: TokenCollection, prefix = ''): FlatTokenCollection[] {
+function flatten (tokens: TokenCollection, prefix = '', depth = Infinity): FlatTokenCollection[] {
   const flattened: FlatTokenCollection[] = []
-  const stack: Array<{ tokens: TokenCollection, prefix: string }> = [{ tokens, prefix }]
+  const stack: { tokens: TokenCollection, prefix: string, depth: number }[] = [{ tokens, prefix, depth }]
 
   while (stack.length > 0) {
-    const { tokens: currentTokens, prefix: currentPrefix } = stack.pop()!
+    const { tokens: currentTokens, prefix: currentPrefix, depth: currentDepth } = stack.pop()!
 
     const meta: Record<string, unknown> = {}
     for (const k in currentTokens) {
@@ -216,7 +226,7 @@ function flatten (tokens: TokenCollection, prefix = ''): FlatTokenCollection[] {
         flattened.push({ id, value: value as TokenAlias })
 
         const inner = value.$value
-        if (isObject(inner)) {
+        if (isObject(inner) && currentDepth > 0) {
           for (const innerKey in inner) {
             if (innerKey.startsWith('$')) continue
 
@@ -227,14 +237,19 @@ function flatten (tokens: TokenCollection, prefix = ''): FlatTokenCollection[] {
             } else if ('$value' in child) {
               flattened.push({ id: childId, value: child as TokenAlias })
             } else {
-              stack.push({ tokens: child as TokenCollection, prefix: childId })
+              stack.push({ tokens: child as TokenCollection, prefix: childId, depth: currentDepth - 1 })
             }
           }
         }
         continue
       }
 
-      stack.push({ tokens: value as TokenCollection, prefix: id })
+      if (currentDepth <= 0) {
+        flattened.push({ id, value: value as unknown as TokenValue })
+        continue
+      }
+
+      stack.push({ tokens: value as TokenCollection, prefix: id, depth: currentDepth - 1 })
     }
   }