themelia-react-ui 1.0.0 → 1.0.1

package/docs/consumer-skill/references/review.md

@@ -0,0 +1,74 @@
+# Composition review and checks
+
+Use after selecting owners, or when auditing a screen. Read only the relevant
+workflow/declarations; this is a review aid, not a new design system.
+
+## Review the task and hierarchy
+
+- Can the user identify the subject, scope and next action? A contextual fact
+  may be repeated for a separate purpose, but should not compete with itself.
+- Do independent records, facts, metrics and editable fields use appropriate
+  owners? Inspect an existing feature before reconstructing its lifecycle.
+- Do primary commands have explicit emphasis and page/collection/record scope?
+  Keep bulk actions tied to selection. Secondary/destructive importance is semantic.
+- Do rows lead with identity and useful decision information? Preserve access
+  to hidden facts without forcing every fact into a tall identity stack.
+- Does each gutter, inset and sibling/copy gap have one owner? Review the whole
+  parent/child chain. A token-backed utility on the wrong owner can still drift.
+- Does the same composition remain readable with long copy, translations,
+  empty/missing values and narrow parent width? Zero and unavailable differ.
+
+These criteria allow different product layouts. Do not impose a universal card
+count, row-line limit, primary button count or one-column form rule.
+
+## Optional source checker
+
+The package ships a read-only script, not an npm bin/global CLI. It needs the
+consumer's TypeScript development dependency and Node matching the package engine:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/check-composition.mjs resources/js/pages resources/js/components
+```
+
+Pass explicit files/directories; `.tsx`, `.ts`, `.jsx` and `.js` are inspected.
+It resolves TypeScript from the app working directory and uses its adjacent
+versioned public index. A complete copied skill works too, after the installed
+identity check. It neither edits files nor installs dependencies. Add this
+command to app CI if useful; repository lint is not automatically installed.
+
+Errors cover unknown package entrypoints/symbols and statically detected overrides
+of protected popup insets or control geometry/typography. Deprecated migration
+owners, nested framed subjects and repeated literal headings produce review
+warnings; warnings alone do not fail CI. Messages identify the owner and remedy.
+Use existing app lint/typechecking for wider language, utility and accessibility
+coverage. The script is deliberately small and does not replace them.
+
+Coverage is limited to direct public imports, aliases/namespaces, and same-file
+static classes/styles/props. Dynamic expressions are reported as unresolved;
+cross-file wrappers, external CSS, render functions and runtime values require
+review. Do not treat an empty report as proof of complete compliance or taste.
+
+## Rendered and interaction evidence
+
+Source checks establish imports and known ownership violations. Separately inspect
+actual rectangles, wrapping, shared insets, title/action alignment and information
+weight at supported parent widths and light/dark scopes. Open relevant menus and
+overlays; a closed trigger cannot prove portal theming or popup geometry.
+
+Execute affected callbacks, keyboard/focus, cancellation, validation, pending
+and failure/retry states. Use deferred requests to observe pending behavior.
+Confirm accepted data changes and draft retention; a toast is only feedback.
+Compare before/after at the same conditions and record unverified limits.
+
+## Application policy
+
+Keep a small app-owned reference linked from its agent instructions: name the
+shell/header/gutter owners, routing/query/form adapters, scope semantics,
+information priorities and relevant local tests. Link current representative
+pages. Preserve permissions, transport, translations and product-specific forms.
+Do not copy the package API manual or edit the packaged skill to encode local policy.
+
+Package declarations define supported props; this skill defines shared composition
+and anatomy; the app defines business meaning and page conventions. If a shared
+owner fails in a valid composition, isolate a reproduction and report the owning
+contract. Do not spread private selectors or copy the control to hide the issue.

package/docs/consumer-skill/references/tokens.json

@@ -1,6 +1,6 @@
 {
   "package": "themelia-react-ui",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "structural": [
     {
       "name": "--space-scale",

package/docs/consumer-skill/references/workflows.md

@@ -8,7 +8,7 @@ The [example manifest](../examples/manifest.json) owns filenames, exported compo
 
 [AccountIndex](../examples/index-table.tsx) exports `AccountIndex`, `AccountIndexProps`, `AccountRow` and `AccountIndexState`. Props are `state`, `onRetry`, `hrefFor(record)` and `onNavigate(href)`. The app drives the discriminated state: `loading`, `error` with a message, or `ready` with records. An empty ready collection renders the table's empty state. `onRetry` starts your loader; it must update app state through loading to ready/error. Stable row IDs belong to the records.
 
-This recipe uses `themelia-react-ui/features/table`, so install `@tanstack/react-table` as an optional peer. Card frames the page; the nested table uses `surface="flat"`. A row action calls your navigation callback with your URL; `href` alone on a table action does not navigate. Supply your router callback or ordinary browser navigation. The library neither requests records nor chooses routes.
+This recipe uses `themelia-react-ui/features/table`, so install `@tanstack/react-table` as an optional peer. Card frames an independent Accounts subject; the nested table uses `surface="flat"`. For a primary route collection use its own native table surface, as in the scoped directory below. A row action calls your navigation callback with your URL; `href` alone on a table action does not navigate. Supply your router callback or ordinary browser navigation. The library neither requests records nor chooses routes.
 
 Verify loading, empty refresh, failure/retry and ready records. Open the row menu with pointer and keyboard, activate Open account, and assert the requested URL. Check narrow overflow and email-link behavior. If you need a presentational table without TanStack features, discover `themelia-react-ui/base/table` and inspect its separate declaration.
 
@@ -18,6 +18,51 @@ Verify loading, empty refresh, failure/retry and ready records. Open the row men
 
 No optional peers are needed. The app supplies the loaded record and owns navigation, locale/provider defaults and permissions. Verify missing email/date/balance, a real minor-unit amount, Edit/Back callbacks, and the one-column mobile/two-column desktop composition in light/dark themes.
 
+## Scoped directory
+
+[ScopedDirectory](../examples/scoped-directory.tsx) demonstrates a primary route
+collection. Page owns Contacts, the fixed business context and the explicit
+primary New contact command. DataTable owns the surface; FilterLayout occupies
+`topbarContent`, optional export occupies `topbarEnd`, and Open contact is a row
+action. ResourceCell owns identity, shared small secondary Text supplies role,
+and Email owns formatting. Other operational facts belong in the contact detail
+reached by `onOpen`; the example does not append every fact to compact identity.
+
+The optional `compact` prop is an app presentation decision from available parent
+width. It keeps email reach in the identity cell and omits the comparison Email
+column, preserving one copy and reachable row actions. This deliberately retains
+one task-critical fact; other metadata stays in detail. Choose the threshold
+from actual content and work-region measurements, not a universal library setting.
+
+The app supplies `scope`, discriminated `state`, controlled `filters`, navigation
+and loading callbacks. `onQueryChange({ scopeId, filters })` preserves fixed
+business context even when criteria clear. It does not request records itself.
+The recipe removes a blank `q` search criterion without normalizing unrelated
+filter types. Native search can emit an empty string; the app owns query meaning.
+The app updates filters/state, ignores stale responses and preserves scope/query
+in pagination URLs. A criteria-driven business selector would be a different
+product contract. The recipe's English labels are example copy: adapt labels,
+criteria and component `strings` for app translation and permissions.
+
+Strict imported declarations require the manifest's optional peers. DataTable
+sorting is disabled because the app's server owns query order. Loading/error
+feedback occupies the empty result region while query context remains mounted;
+accepted records replace it. Use the public loading/preview owner if retaining
+previous results is required by your app. Avoid stale pagination metadata during
+loading/errors. Run the same query with loading, failure, retry and empty results.
+
+Verify one contextual lead, primary command, query/clear scope retention,
+row-menu navigation, server page callbacks and long-name/mobile containment.
+Opening a record preserves access to supporting facts. Integrated queries and
+separate query regions are both supported; choose by task and keep one owner.
+
+Keep DataTable column/action definitions stable when unrelated parent feedback
+changes. Changing a cell renderer's identity can remount its menu trigger and
+lose return focus. This recipe memoizes row actions by `onOpen`; the app keeps
+that callback stable when its meaning is unchanged. Stabilize these lifecycle
+inputs deliberately, not every object. A real record/scope change can replace
+definitions; the app then chooses appropriate destination focus.
+
 ## Validated editing
 
 [AccountEdit](../examples/edit.tsx) exports `AccountEdit`, `AccountEditProps` and `AccountEditValue`. Supply `initial`, `onSave(value): Promise<AccountEditValue>` and `onCancel()`. Mount with `key={initial.id}` when switching records. The draft is local to that mount; resetting the same record's draft deliberately also requires a new key or your own controlled adaptation.
@@ -37,3 +82,54 @@ Your delete callback owns persistence and record removal. Reject failures instea
 Verify open/title/description, trapped keyboard focus, Cancel/Escape without a deletion callback, pending dismissal prevention, rejected callback with an open error, retry and successful closure, exactly one backend effect, and trigger focus restoration. Check the opened error dialog in dark/mobile as well as light/desktop. Do not infer these interactions from typechecking or screenshots.
 
 The existing [AccountComposition](../examples/composition.tsx) remains a basic Card/ActionDialog composition with `save(name): Promise<void>`. Its callback must reject on failure; the app owns persistence. The four recipes above add progressive collection/detail/edit/delete ownership without changing that example's contract.
+
+## Task summaries, usage and inline editing
+
+[Workspace summary](../examples/planning-usage-edit.tsx) composes three focused
+owners. `TaskCard` from `themelia-react-ui/blocks/planning` owns the explicit Card
+surface, completion summary, disclosure and controlled subtask proposals.
+Update `items` after `onItemCompletedChange`; supply each item's `busy` or
+`error` from your persistence lifecycle. Workflow status, due-date formatting,
+assignment and Open navigation remain application data/callbacks.
+
+Click passive header content or use the native caret (pointer, Enter or Space)
+to request expansion. Both respect `expanded`/`onExpandedChange` and `disabled`;
+header clicks focus the caret. Subtask and footer actions remain independent.
+The block owns the segmented progress drawing, completion strikethrough and
+compact checklist insets. Its progress value follows accepted `items`, including
+undo; workflow status stays separate. Reduced motion disables the ring animation.
+
+`UsageCard` from `themelia-react-ui/blocks/analytics/usage-card` is a standalone
+quota/analytics composition with no optional chart dependency. Supply matching
+`data`, `period` and `status` after `onPeriodChange`; cancel or ignore stale
+application requests. `limit: null` means unlimited, omitted limits or values
+mean unavailable, and zero is real data. Category percentages describe shares
+of reported usage; bounded graphics never hide actual over-quota amounts.
+Daily data is chronological application data with text equivalents. The block
+owns no subscription or billing requests; `footerAction` is application content.
+
+`InlineEdit` from `themelia-react-ui/base/inline-edit` uses our native Input or
+Textarea. Supply `onSave(value, { signal })` for asynchronous persistence and
+update a controlled saved value through `onValueChange`. Required/validation
+checks apply when saving a draft. Parent forms serialize the committed value
+through `name`; they own validation of their complete stored data. Enter saves
+a single line, Control/Command Enter saves multiline text, and Escape cancels.
+Cancellation invalidates late UI results and aborts the supplied signal; the
+application owns actual transport and server effects. Read-only display stays
+passive. Use Card at a composition boundary for a framed field section.
+
+Display and editing share the Input frame and `size`, `invalid`, `loading`,
+`clearable`, `onClear` and `showCharacterCount` APIs. The stable field/action
+grid transitions width and honors reduced motion; multiline actions form a
+centered column. Use `inputProps`/`textareaProps` for native editor attributes,
+adornments, resizing and control-specific strings. State/value/ref/form ownership
+stays with InlineEdit. Native constraints run on Save; uncommitted controls are
+isolated from the parent form. External loading retains a draft while disabling
+edits/save, and leaves cancellation available.
+
+The field/action gap uses the existing `lg` spacing step; the action group uses
+`xs`. Single-line actions form a horizontal pair and multiline actions a centered
+column. Keep these library-owned controls and geometry instead of replacing
+them with app-styled fields. Verify cancellation during persistence, retained
+drafts after rejection, native constraints, committed FormData, controlled
+expansion, checkbox/Open independence and async period retry in your app.

package/docs/consumer-skill/scripts/check-composition.mjs

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { validateIndex } from './discovery.mjs';
+import { analyzeComposition } from './composition-policy.mjs';
+
+try {
+  const targets = process.argv.slice(2);
+  if (!targets.length || targets.some(target => target.startsWith('-'))) throw new Error('Pass explicit source files/directories; no flags or automatic app-wide scan.');
+  const requireFromApp = createRequire(path.join(process.cwd(), 'package.json'));
+  const ts = requireFromApp('typescript');
+  const index = validateIndex(JSON.parse(fs.readFileSync(new URL('../references/public-api.json', import.meta.url), 'utf8')));
+  const files = new Set();
+  function collect(target) {
+    const info = fs.lstatSync(target);
+    if (info.isSymbolicLink()) throw new Error(`Use a real source path instead of a symlink: ${target}`);
+    if (info.isDirectory()) {
+      for (const entry of fs.readdirSync(target).sort()) if (!['node_modules', '.git', 'dist', 'build'].includes(entry)) collect(path.join(target, entry));
+    } else if (/\.[jt]sx?$/.test(target) && !/\.d\.ts$/.test(target)) files.add(path.resolve(target));
+  }
+  targets.forEach(collect);
+  if (!files.size) throw new Error('No supported source files found in the supplied paths.');
+  const reports = [...files].sort().map(filename => analyzeComposition(fs.readFileSync(filename, 'utf8'), { filename, index, ts }));
+  const findings = reports.flatMap(report => report.findings);
+  const errors = findings.filter(finding => finding.severity === 'error').length;
+  process.stdout.write(JSON.stringify({ package: index.package, version: index.version, files: files.size, errors, warnings: findings.length - errors, findings, unresolved: reports.flatMap(report => report.unresolved), limits: 'Direct public imports and same-file static JSX only; external CSS, cross-file wrappers and dynamic values require review.' }, null, 2) + '\n');
+  process.exitCode = errors ? 1 : 0;
+} catch (error) {
+  process.stderr.write(`check-composition: ${error.message}\nRun from the consumer app with its TypeScript development dependency installed.\n`);
+  process.exitCode = 1;
+}

package/docs/consumer-skill/scripts/composition-policy.mjs

@@ -0,0 +1,155 @@
+import { surfaceParts, surfaceForwarders, paddingClass, paddingProperty, utility } from './surface-policy.mjs';
+
+const controlNames = /^(?:Base)?(?:Button|ButtonLink|IconButton)$|^(Input|InputGroupInput|Textarea|SelectTrigger|ComboboxTrigger)$/;
+const controlFamilies = new Set(['buttons', 'text-inputs', 'choice-inputs', 'combobox']);
+const fixedControlClass = /^(?:h|min-h|size|p[xytrblse]?)-|^rounded-(?:xs|sm|md|lg|xl|[2-9]xl|\[)|^text-(?:xs|sm|base|lg|xl|[2-9]xl|\[(?:length:|[\d.]+(?:px|rem|em)))|^(?:font|leading|tracking)-/;
+const controlStyle = /^(height|minHeight|fontSize|fontWeight|lineHeight|letterSpacing|borderRadius)$/;
+
+/** Small static review: TypeScript is supplied by the app, never a runtime peer. */
+export function analyzeComposition(text, { filename, index, ts }) {
+  const kind = /\.jsx?$/.test(filename) ? ts.ScriptKind.JSX : filename.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+  const source = ts.createSourceFile(filename, text, ts.ScriptTarget.Latest, true, kind);
+  const families = new Map(index.families.map(owner => [owner.import, owner]));
+  const bindings = new Map();
+  const namespaces = new Map();
+  const declarations = new Map();
+  const findings = [];
+  const unresolved = [];
+  const seen = new Set();
+  const add = (node, rule, severity, message) => {
+    const position = source.getLineAndCharacterOfPosition(node.getStart(source));
+    const key = `${node.pos}:${rule}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    findings.push({ file: filename, line: position.line + 1, column: position.character + 1, rule, severity, message });
+  };
+  const unknown = node => {
+    const key = `${node.pos}:unresolved`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    const position = source.getLineAndCharacterOfPosition(node.getStart(source));
+    unresolved.push({ file: filename, line: position.line + 1, expression: node.getText(source).slice(0, 120) });
+  };
+  const resolve = (node, visiting = new Set()) => {
+    if (!node || visiting.has(node)) return undefined;
+    visiting.add(node);
+    if (ts.isIdentifier(node)) return resolve(declarations.get(node.text), visiting);
+    if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) return resolve(node.expression, visiting);
+    return node;
+  };
+  const properties = (expression, mark = true, visited = new Set()) => {
+    const node = resolve(expression);
+    if (!node || !ts.isObjectLiteralExpression(node) || visited.has(node)) {
+      if (mark && expression) unknown(expression);
+      return [];
+    }
+    visited.add(node);
+    return node.properties.flatMap(property => {
+      if (ts.isSpreadAssignment(property)) return properties(property.expression, mark, visited);
+      const name = property.name;
+      const key = ts.isComputedPropertyName(name) ? resolve(name.expression) : name;
+      if (!key || !(ts.isIdentifier(key) || ts.isStringLiteralLike(key))) {
+        if (mark) unknown(property);
+        return [];
+      }
+      return [[key.text, ts.isShorthandPropertyAssignment(property) ? property.name : property.initializer]];
+    });
+  };
+  const classStrings = (expression, visited = new Set()) => {
+    const node = resolve(expression);
+    if (!node || visited.has(node)) { if (expression) unknown(expression); return []; }
+    visited.add(node);
+    if (ts.isStringLiteralLike(node)) return [node.text];
+    if (ts.isConditionalExpression(node)) return [...classStrings(node.whenTrue, visited), ...classStrings(node.whenFalse, visited)];
+    if (ts.isBinaryExpression(node) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(node.operatorToken.kind)) return classStrings(node.right, visited);
+    if (ts.isArrayLiteralExpression(node)) return node.elements.flatMap(item => classStrings(item, visited));
+    if (ts.isCallExpression(node) && /^(cn|clsx|classNames|twMerge)$/.test(node.expression.getText(source))) return node.arguments.flatMap(item => classStrings(item, visited));
+    if ([ts.SyntaxKind.FalseKeyword, ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.NullKeyword].includes(node.kind)) return [];
+    unknown(expression);
+    return [];
+  };
+  const literal = expression => {
+    const node = resolve(expression);
+    return node && ts.isStringLiteralLike(node) ? node.text : undefined;
+  };
+  function importOwner(node, specifier) {
+    if (specifier !== index.package && !specifier.startsWith(index.package + '/')) return;
+    if (index.stylesheets?.includes(specifier)) return;
+    const family = families.get(specifier);
+    if (!family) { add(node, 'public-import', 'error', `No published owner for ${specifier}; discover the version-matched public entrypoint.`); return; }
+    const names = ts.isImportDeclaration(node) ? node.importClause?.namedBindings : node.exportClause;
+    if (ts.isImportDeclaration(node) && node.importClause?.name && !family.symbols.includes('default')) add(node.importClause.name, 'public-symbol', 'error', `${specifier} has no default export; use its named public symbols.`);
+    const elements = names && (ts.isNamedImports(names) || ts.isNamedExports(names)) ? names.elements : [];
+    for (const item of elements) {
+      const symbol = (item.propertyName ?? item.name).text;
+      if (!family.symbols.includes(symbol)) add(item, 'public-symbol', 'error', `${specifier} does not export ${symbol}; inspect its declaration.`);
+      if (ts.isImportDeclaration(node)) bindings.set(item.name.text, { symbol, import: specifier });
+    }
+    if (names && ts.isNamespaceImport(names)) namespaces.set(names.name.text, specifier);
+  }
+  function gather(node) {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) declarations.set(node.name.text, node.initializer);
+    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) importOwner(node, node.moduleSpecifier.text);
+    if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument) && ts.isStringLiteralLike(node.argument.literal)) importOwner(node, node.argument.literal.text);
+    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && ts.isStringLiteralLike(node.arguments[0])) importOwner(node, node.arguments[0].text);
+    ts.forEachChild(node, gather);
+  }
+  gather(source);
+  for (const diagnostic of source.parseDiagnostics) add(source, 'syntax', 'error', ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
+  const ownerFor = tag => {
+    if (bindings.has(tag)) return bindings.get(tag);
+    const [namespace, symbol] = tag.split('.');
+    const specifier = namespaces.get(namespace);
+    return specifier && symbol ? { symbol, import: specifier } : undefined;
+  };
+  const attributes = node => node.attributes.properties.flatMap(attribute => {
+    if (ts.isJsxSpreadAttribute(attribute)) return properties(attribute.expression);
+    if (!attribute.initializer) return [[attribute.name.getText(source), undefined]];
+    const expression = ts.isJsxExpression(attribute.initializer) ? attribute.initializer.expression : attribute.initializer;
+    return [[attribute.name.getText(source), expression]];
+  });
+  function visit(node, parents = []) {
+    if (ts.isJsxElement(node)) {
+      const element = node.openingElement;
+      const context = inspect(element, parents);
+      for (const child of node.children) visit(child, context ? [...parents, context] : parents);
+      // JSX in props is a separate region, not a child frame.
+      for (const attribute of element.attributes.properties) ts.forEachChild(attribute, child => visit(child, parents));
+      return;
+    }
+    if (ts.isJsxSelfClosingElement(node)) inspect(node, parents);
+    ts.forEachChild(node, child => visit(child, parents));
+  }
+  function inspect(node, parents) {
+    const owner = ownerFor(node.tagName.getText(source));
+    if (!owner) return;
+    if (!families.get(owner.import)?.symbols.includes(owner.symbol)) {
+      add(node, 'public-symbol', 'error', `${owner.import} does not export ${owner.symbol}.`);
+      return;
+    }
+    const props = new Map(attributes(node));
+    const family = owner.import.split('/base/')[1];
+    const anatomy = surfaceParts[family]?.test(owner.symbol);
+    const forwarder = surfaceForwarders[family] === owner.symbol;
+    const control = controlFamilies.has(family) && controlNames.test(owner.symbol);
+    for (const name of ['className', 'contentClassName']) {
+      if (!props.has(name)) continue;
+      const classes = classStrings(props.get(name)).flatMap(value => value.split(/\s+/)).map(utility);
+      if ((anatomy || forwarder && name === 'contentClassName') && classes.some(value => paddingClass.test(value))) add(node, 'surface-padding', 'error', `${owner.symbol}: use inset/type/density and public regions; padding overrides replace owned anatomy.`);
+      if (control && name === 'className' && classes.some(value => fixedControlClass.test(value))) add(node, 'control-anatomy', 'error', `${owner.symbol}: use its size/variant props; preserve shared control height, inset, corners and typography.`);
+    }
+    if (props.has('style')) for (const [name] of properties(props.get('style'))) {
+      if (anatomy && paddingProperty.test(name)) add(node, 'surface-padding', 'error', `${owner.symbol}: ${name} replaces the region inset; use its public surface props.`);
+      if (control && (paddingProperty.test(name) || controlStyle.test(name))) add(node, 'control-anatomy', 'error', `${owner.symbol}: ${name} belongs to shared control geometry/typography.`);
+    }
+    if (['SmartCard', 'ContentBlock'].includes(owner.symbol)) add(node, 'deprecated-owner', 'warning', `${owner.symbol} is a migration owner; prefer Card for new compositions.`);
+    const framed = ['Card', 'SmartCard', 'ContentBlock', 'DataTable', 'DataView'].includes(owner.symbol) && literal(props.get('surface')) !== 'flat';
+    if (framed && parents.some(parent => parent.framed)) add(node, 'nested-surface', 'warning', `${owner.symbol} is inside a framed owner. Review subject boundaries; use surface="flat" when the parent owns the frame.`);
+    const header = properties(props.get('header'), false);
+    const title = literal(props.get('title')) ?? literal(new Map(header).get('title'));
+    if (title && parents.some(parent => parent.title === title)) add(node, 'duplicate-heading', 'warning', `The heading "${title}" repeats its ancestor. Keep one route/subject title unless a distinct task warrants repetition.`);
+    return { framed, title };
+  }
+  visit(source);
+  return { findings, unresolved };
+}

package/docs/consumer-skill/scripts/discovery.mjs

@@ -8,6 +8,7 @@ const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 export function validateIndex(index) {
   requireFormat(index?.schemaVersion === 1 && index?.discoveryVersion === 1, 'unsupported schema/format; expected schemaVersion 1 and discoveryVersion 1');
   requireFormat(text(index.package) && text(index.version) && Array.isArray(index.families), 'package, version and families are required');
+  if (index.stylesheets !== undefined) requireFormat(stringList(index.stylesheets) && index.stylesheets.every(file => file.startsWith(index.package + '/') && file.endsWith('.css') && !file.includes('..')), 'invalid public stylesheets');
   const seen = new Set();
   for (const family of index.families) {
     requireFormat(text(family?.import) && (family.import === index.package || family.import.startsWith(`${index.package}/`)) && !/[\\\s]|(?:^|\/)\.\.(?:\/|$)/.test(family.import), 'invalid public import');
@@ -70,7 +71,11 @@ export function findComponents(index, { query, layer = null, limit = 5 }) {
     // AND matching prevents a familiar term from inventing results for an
     // otherwise unknown query. Avoidance/alternatives do not recommend owners.
     if (!exactImport && !matchedSymbols.length && !terms.every(term => haystack.includes(term))) continue;
-    const score = exactImport ? 10000 : matchedSymbols.length ? 9000 : terms.reduce((sum, term) => sum + (family.guidance.some(guide => normalized(guide.title).includes(term)) ? 20 : family.tags.some(tag => normalized(tag).includes(term)) ? 10 : 1), 0);
+    // A dedicated, documented owner precedes an aggregate re-export of the
+    // same symbol. Explicit import queries still select the requested family.
+    const documentedSymbol = family.guidance.some(guide => guide.sections.some(section => section.symbols.some(symbol => normalized(symbol) === needle)));
+    const exactIntent = family.aliases.some(alias => normalized(alias) === needle);
+    const score = exactImport ? 10000 : matchedSymbols.length ? 9000 + Number(documentedSymbol) : exactIntent ? 8000 : terms.reduce((sum, term) => sum + (family.guidance.some(guide => normalized(guide.title).includes(term)) ? 20 : family.tags.some(tag => normalized(tag).includes(term)) ? 10 : 1), 0);
     const guidance = family.guidance.map(guide => ({ guide, score: terms.filter(term => guideText(guide).includes(term)).length })).sort((a, b) => b.score - a.score || compare(a.guide.title, b.guide.title)).slice(0, 3).map(({ guide }) => guide);
     ranked.push({ score, import: family.import, declaration: family.declaration, layer: family.layer, responsibility: family.responsibility, optionalPeers: family.optionalPeers, match: exactImport ? 'import' : matchedSymbols.length ? 'symbol' : 'intent', matchedSymbols, guidance });
   }

package/docs/consumer-skill/scripts/surface-policy.mjs

@@ -0,0 +1,22 @@
+// One public anatomy vocabulary, shared by repository and opt-in consumer checks.
+export const surfaceParts = {
+  popover: /^(PopoverContent|PopoverHeader|PopoverFooter)$/,
+  command: /^Command(Input|List|Group|Item|Empty|Separator)?$/,
+  navigation: /^DropdownMenu(Content|SubContent|Label|Item|LinkItem|SubTrigger|CheckboxItem|RadioItem|Separator)$/,
+  'choice-inputs': /^SelectPopup(Content|Group|Item|Label|Separator)?$/,
+  combobox: /^Combobox(Popup|Content|List|Item|GroupLabel|Separator)$/,
+};
+export const surfaceForwarders = { 'choice-inputs': 'Select', 'popover-menu': 'PopoverMenu', 'action-menu': 'ActionMenu' };
+export const paddingClass = /^(?:p[xytrblse]?|p(?:bs|be)|padding)-|^\[padding/;
+export const paddingProperty = /^padding(?:Inline|Block)?(?:Start|End)?$|^padding(?:Top|Right|Bottom|Left)$|^padding-(?:(?:inline|block)(?:-(?:start|end))?|top|right|bottom|left)$/;
+
+export function utility(token) {
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < token.length; i++) {
+    if (token[i] === '[' || token[i] === '(') depth++;
+    if (token[i] === ']' || token[i] === ')') depth--;
+    if (token[i] === ':' && depth === 0) start = i + 1;
+  }
+  return token.slice(start).replace(/^!|!$/g, '');
+}

package/package.json

@@ -1,12 +1,21 @@
 {
   "name": "themelia-react-ui",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A composable React UI library for modern admin applications, built on Base UI and Tailwind with shadcn-compatible themes, shared design tokens, reusable layouts, blocks and workflows.",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "keywords": ["react", "ui", "admin", "dashboard", "base-ui", "tailwindcss", "shadcn", "design-system"],
+  "keywords": [
+    "react",
+    "ui",
+    "admin",
+    "dashboard",
+    "base-ui",
+    "tailwindcss",
+    "shadcn",
+    "design-system"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nicolasvlachos/themelia-react-ui.git"
@@ -413,6 +422,18 @@
     "./features/questionnaire": {
       "types": "./dist/components/features/questionnaire/index.d.ts",
       "import": "./dist/features/questionnaire.js"
+    },
+    "./base/inline-edit": {
+      "types": "./dist/components/base/inline-edit/index.d.ts",
+      "import": "./dist/base/inline-edit.js"
+    },
+    "./blocks/planning": {
+      "types": "./dist/components/blocks/planning/index.d.ts",
+      "import": "./dist/blocks/planning.js"
+    },
+    "./blocks/analytics/usage-card": {
+      "types": "./dist/components/blocks/analytics/usage-card/index.d.ts",
+      "import": "./dist/blocks/analytics/usage-card.js"
     }
   },
   "scripts": {
@@ -442,7 +463,7 @@
     "check:maps": "node scripts/test-client-boundaries.mjs --built",
     "build:docs": "node scripts/build-static-docs.mjs",
     "check:static-docs": "node scripts/check-static-docs.mjs",
-    "check:agent": "node --test scripts/test-consumer-discovery.mjs scripts/test-consumer-skill-assets.mjs scripts/test-static-docs.mjs scripts/test-fixture-install.mjs && npm run check:skill",
+    "check:agent": "node --test scripts/test-consumer-discovery.mjs scripts/test-consumer-composition.mjs scripts/test-consumer-skill-assets.mjs scripts/test-static-docs.mjs scripts/test-fixture-install.mjs && npm run check:skill",
     "check:release": "npm run check:all && npm run check:agent && npm run build:docs && npm run check:static-docs"
   },
   "peerDependencies": {

package/dist/affordance-geometry.generated-DXl-Zb3Z.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"affordance-geometry.generated-DXl-Zb3Z.js","names":["affordanceGeometry","\"navigationGuideStart\"","\"clearEnd\"","\"sm\"","\"md\"","\"lg\"","\"clearPadding\"","\"togglePadding\"","\"largeIconStart\"","\"largeIconEnd\"","\"overlayClose\"","\"overlayHeader\""],"sources":["../src/lib/affordance-geometry.generated.ts"],"sourcesContent":["/* Generated by scripts/primitive-geometry.mjs; recipes, not theme roots. */\nexport const affordanceGeometry = {\n  \"navigationGuideStart\": \"ms-[calc(var(--control-x)*0.8333333*var(--space-scale)+var(--icon)*0.75*var(--space-scale)/2)]\",\n  \"clearEnd\": {\n    \"sm\": \"end-[calc(var(--control-x)*0.8333333*var(--space-scale))]\",\n    \"md\": \"end-[calc(var(--control-x)*var(--space-scale))]\",\n    \"lg\": \"end-[calc(var(--control-x)*var(--space-scale))]\"\n  },\n  \"clearPadding\": {\n    \"sm\": \"pe-[calc(var(--control-x)*0.8333333*var(--space-scale)+1.375rem*var(--density-scale)+0.375rem*var(--space-scale))]\",\n    \"md\": \"pe-[calc(var(--control-x)*var(--space-scale)+1.375rem*var(--density-scale)+0.375rem*var(--space-scale))]\",\n    \"lg\": \"pe-[calc(var(--control-x)*var(--space-scale)+1.375rem*var(--density-scale)+0.375rem*var(--space-scale))]\"\n  },\n  \"togglePadding\": \"pe-[calc(1.375rem*var(--density-scale)+0.625rem*var(--space-scale))]\",\n  \"largeIconStart\": \"ps-[calc((var(--control-x)+var(--icon)*1.25+0.5rem)*var(--space-scale))]\",\n  \"largeIconEnd\": \"pe-[calc((var(--control-x)+var(--icon)*1.25+0.5rem)*var(--space-scale))]\",\n  \"overlayClose\": \"absolute top-[calc(var(--surface-y)*var(--space-scale))] end-[calc(var(--surface-x)*var(--space-scale))]\",\n  \"overlayHeader\": \"[[data-slot$=-content]:has(>[data-overlay-close])>&]:pe-[calc(var(--surface-x)*var(--space-scale)+var(--height-action)*0.8888889*var(--density-scale)+0.5rem*var(--space-scale))]\"\n} as const;\n"],"mappings":";AACA,IAAaA,IAAqB;CAChCC,sBAAwB;CACxBC,UAAY;EACVC,IAAM;EACNC,IAAM;EACNC,IAAM;CACR;CACAC,cAAgB;EACdH,IAAM;EACNC,IAAM;EACNC,IAAM;CACR;CACAE,eAAiB;CACjBC,gBAAkB;CAClBC,cAAgB;CAChBC,cAAgB;CAChBC,eAAiB;AACnB"}

package/dist/avatar-CsnWaYmt.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"avatar-CsnWaYmt.js","names":["Avatar","AvatarPrimitive","AvatarImage","AvatarFallback","AvatarBadge","AvatarGroup","AvatarGroupCount","Avatar","React","PrimitiveAvatar","PrimitiveAvatarImage","PrimitiveAvatarFallback","PrimitiveAvatarBadge","PrimitiveAvatarGroup","PrimitiveAvatarGroupCount","Avatar","resolveComponentScale","useDensityConfig","cn","Text","formatInitials","React$1","Avatar$2","props","Avatar","size","className","AvatarImage$1","AvatarFallback$1","AvatarBadge$1","AvatarGroup$1","AvatarGroupCount$1","AVATAR_SIZE_CLASSNAMES","getPrimitiveSize","Avatar$1","sizeProp","defaultScale","AvatarImage","AvatarFallback","children","AvatarBadge","AvatarGroup","AvatarGroupCount","FALLBACK_TONES","FALLBACK_TONE_CLASSNAMES","pickFallbackTone","override","seed","s","c","StackedAvatars","visible","users","max","overflow","overflowContent","overflowFormatter","initials","user","fallbackTone","index","avatarClassName","showOverflow"],"sources":["../src/components/ui/avatar.tsx","../src/components/base/avatar/avatar.tsx","../src/components/base/avatar/stacked-avatars.tsx"],"sourcesContent":["import { Avatar as AvatarPrimitive } from \"@base-ui/react/avatar\"\nimport * as React from \"react\"\n\nimport { cn } from \"../../lib/utils\"\n\nfunction Avatar({\n  className,\n  size = \"default\",\n  ...props\n}: AvatarPrimitive.Root.Props & {\n  size?: \"default\" | \"sm\" | \"lg\"\n}) {\n  return (\n    <AvatarPrimitive.Root\n      data-slot=\"avatar\"\n      data-size={size}\n      className={cn(\n        \"size-8 rounded-full after:rounded-full data-[size=lg]:size-10 data-[size=sm]:size-6 after:border-border group/avatar relative flex shrink-0 select-none after:absolute after:inset-0 after:border after:mix-blend-darken dark:after:mix-blend-lighten\",\n        className\n      )}\n      {...props}\n    />\n  )\n}\n\nfunction AvatarImage({ className, ...props }: AvatarPrimitive.Image.Props) {\n  return (\n    <AvatarPrimitive.Image\n      data-slot=\"avatar-image\"\n      className={cn(\n        \"rounded-full aspect-square size-full object-cover\",\n        className\n      )}\n      {...props}\n    />\n  )\n}\n\nfunction AvatarFallback({\n  className,\n  ...props\n}: AvatarPrimitive.Fallback.Props) {\n  return (\n    <AvatarPrimitive.Fallback\n      data-slot=\"avatar-fallback\"\n      className={cn(\n        \"bg-muted text-muted-foreground rounded-full flex size-full items-center justify-center text-sm group-data-[size=sm]/avatar:text-xs\",\n        className\n      )}\n      {...props}\n    />\n  )\n}\n\nfunction AvatarBadge({ className, ...props }: React.ComponentProps<\"span\">) {\n  return (\n    <span\n      data-slot=\"avatar-badge\"\n      className={cn(\n        \"bg-primary text-primary-foreground ring-background absolute right-0 bottom-0 z-10 inline-flex items-center justify-center rounded-full bg-blend-color ring-2 select-none\",\n        \"group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden\",\n        \"group-data-[size=default]/avatar:size-2.5 group-data-[size=default]/avatar:[&>svg]:size-2\",\n        \"group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2\",\n        className\n      )}\n      {...props}\n    />\n  )\n}\n\nfunction AvatarGroup({ className, ...props }: React.ComponentProps<\"div\">) {\n  return (\n    <div\n      data-slot=\"avatar-group\"\n      className={cn(\n        \"*:data-[slot=avatar]:ring-background group/avatar-group flex -space-x-2 *:data-[slot=avatar]:ring-2\",\n        className\n      )}\n      {...props}\n    />\n  )\n}\n\nfunction AvatarGroupCount({\n  className,\n  ...props\n}: React.ComponentProps<\"div\">) {\n  return (\n    <div\n      data-slot=\"avatar-group-count\"\n      className={cn(\"bg-muted text-muted-foreground size-8 rounded-full text-sm group-has-data-[size=lg]/avatar-group:size-10 group-has-data-[size=sm]/avatar-group:size-6 [&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 group-has-data-[size=sm]/avatar-group:[&>svg]:size-3 ring-background relative flex shrink-0 items-center justify-center ring-2\", className)}\n      {...props}\n    />\n  )\n}\n\nexport {\n  Avatar,\n  AvatarImage,\n  AvatarFallback,\n  AvatarGroup,\n  AvatarGroupCount,\n  AvatarBadge,\n}\n","/**\n * Avatar — tokenized base wrapper around the shadcn/Base UI avatar primitive.\n * Public sizing uses the shared component scale.\n */\nimport * as React from 'react';\n\nimport {\n\tAvatar as PrimitiveAvatar,\n\tAvatarBadge as PrimitiveAvatarBadge,\n\tAvatarFallback as PrimitiveAvatarFallback,\n\tAvatarGroup as PrimitiveAvatarGroup,\n\tAvatarGroupCount as PrimitiveAvatarGroupCount,\n\tAvatarImage as PrimitiveAvatarImage,\n} from '../../ui/avatar';\nimport { useDensityConfig, type ComponentScale } from '../../../lib/ui-provider';\nimport { resolveComponentScale } from '../../../lib/ui-provider/scale';\nimport { Text } from '../../typography';\nimport { cn } from '../../../lib/utils';\n\nexport type AvatarSize = ComponentScale;\n\nexport interface AvatarProps\n\textends Omit<React.ComponentPropsWithoutRef<typeof PrimitiveAvatar>, 'size'> {\n\t/** Size preset. */\n\tsize?: AvatarSize;\n}\n\nexport type AvatarImageProps = React.ComponentPropsWithoutRef<typeof PrimitiveAvatarImage>;\nexport type AvatarFallbackProps = React.ComponentPropsWithoutRef<typeof PrimitiveAvatarFallback>;\nexport type AvatarBadgeProps = React.ComponentPropsWithoutRef<typeof PrimitiveAvatarBadge>;\nexport type AvatarGroupProps = React.ComponentPropsWithoutRef<typeof PrimitiveAvatarGroup>;\nexport type AvatarGroupCountProps = React.ComponentPropsWithoutRef<typeof PrimitiveAvatarGroupCount>;\n\nconst AVATAR_SIZE_CLASSNAMES: Record<AvatarSize, string> = {\n\tsm: 'size-avatar-sm',\n\tmd: 'size-avatar',\n\tlg: 'size-avatar-lg',\n};\n\nfunction getPrimitiveSize(size: AvatarSize): NonNullable<React.ComponentPropsWithoutRef<typeof PrimitiveAvatar>['size']> {\n\tif (size === 'sm') return 'sm';\n\tif (size === 'lg') return 'lg';\n\treturn 'default';\n}\n\nconst Avatar = React.forwardRef<React.ElementRef<typeof PrimitiveAvatar>, AvatarProps>(\n\t({ size: sizeProp, className, ...props }, ref) => {\n\t\tconst { defaultScale } = useDensityConfig();\n\t\tconst size = resolveComponentScale(sizeProp, defaultScale);\n\t\treturn (\n\t\t\t<PrimitiveAvatar\n\t\t\t\tref={ref}\n\t\t\t\tsize={getPrimitiveSize(size)}\n\t\t\t\tdata-scale={size}\n\t\t\t\tclassName={cn('avatar--component', AVATAR_SIZE_CLASSNAMES[size], className)}\n\t\t\t\t{...props}\n\t\t\t/>\n\t\t);\n\t},\n);\nAvatar.displayName = 'Avatar';\n\nconst AvatarImage = React.forwardRef<React.ElementRef<typeof PrimitiveAvatarImage>, AvatarImageProps>(\n\t({ className, ...props }, ref) => (\n\t\t<PrimitiveAvatarImage\n\t\t\tref={ref}\n\t\t\tclassName={cn('avatar--image', className)}\n\t\t\t{...props}\n\t\t/>\n\t),\n);\nAvatarImage.displayName = 'AvatarImage';\n\nconst AvatarFallback = React.forwardRef<React.ElementRef<typeof PrimitiveAvatarFallback>, AvatarFallbackProps>(\n\t({ className, children, ...props }, ref) => (\n\t\t<PrimitiveAvatarFallback\n\t\t\tref={ref}\n\t\t\tclassName={cn('avatar--fallback text-xs font-medium leading-none', className)}\n\t\t\t{...props}\n\t\t>\n\t\t\t{typeof children === 'string' || typeof children === 'number' || typeof children === 'bigint' ? (\n\t\t\t\t<Text tag=\"span\" size=\"inherit\" weight=\"medium\" lineHeight=\"none\" className=\"text-inherit\">\n\t\t\t\t\t{children}\n\t\t\t\t</Text>\n\t\t\t) : children}\n\t\t</PrimitiveAvatarFallback>\n\t),\n);\nAvatarFallback.displayName = 'AvatarFallback';\n\nconst AvatarBadge = React.forwardRef<React.ElementRef<typeof PrimitiveAvatarBadge>, AvatarBadgeProps>(\n\t({ className, ...props }, ref) => (\n\t\t<PrimitiveAvatarBadge\n\t\t\tref={ref}\n\t\t\tclassName={cn('avatar--badge', className)}\n\t\t\t{...props}\n\t\t/>\n\t),\n);\nAvatarBadge.displayName = 'AvatarBadge';\n\nconst AvatarGroup = React.forwardRef<React.ElementRef<typeof PrimitiveAvatarGroup>, AvatarGroupProps>(\n\t({ className, ...props }, ref) => (\n\t\t<PrimitiveAvatarGroup\n\t\t\tref={ref}\n\t\t\tclassName={cn('avatar-group--component', className)}\n\t\t\t{...props}\n\t\t/>\n\t),\n);\nAvatarGroup.displayName = 'AvatarGroup';\n\nconst AvatarGroupCount = React.forwardRef<React.ElementRef<typeof PrimitiveAvatarGroupCount>, AvatarGroupCountProps>(\n\t({ className, children, ...props }, ref) => (\n\t\t<PrimitiveAvatarGroupCount\n\t\t\tref={ref}\n\t\t\tclassName={cn(\n\t\t\t\t'avatar-group-count--component size-avatar text-xs',\n\t\t\t\t'group-has-data-[size=sm]/avatar-group:size-avatar-sm',\n\t\t\t\tclassName,\n\t\t\t)}\n\t\t\t{...props}\n\t\t>\n\t\t\t{typeof children === 'string' || typeof children === 'number' || typeof children === 'bigint' ? (\n\t\t\t\t<Text tag=\"span\" size=\"inherit\" weight=\"medium\" lineHeight=\"none\" className=\"text-inherit\">\n\t\t\t\t\t{children}\n\t\t\t\t</Text>\n\t\t\t) : children}\n\t\t</PrimitiveAvatarGroupCount>\n\t),\n);\nAvatarGroupCount.displayName = 'AvatarGroupCount';\n\nexport {\n\tAvatar,\n\tAvatarImage,\n\tAvatarFallback,\n\tAvatarGroup,\n\tAvatarGroupCount,\n\tAvatarBadge,\n};\n","/**\n * StackedAvatars — overlapping avatar group with optional `+N` overflow chip,\n * configurable size, and an optional semantic `tone` for fallbacks (initials)\n * when the consumer hasn't passed `imageUrl`.\n *\n * Wraps the shadcn AvatarGroup primitive with library-default sizes and a\n * deterministic tone picker so fallbacks stay stable without raw hue utilities.\n */\nimport * as React from 'react';\nimport {\n\tAvatar,\n\tAvatarFallback,\n\tAvatarGroup,\n\tAvatarGroupCount,\n\tAvatarImage,\n} from './avatar';\nimport { formatInitials } from '../../primitives/initials-format';\nimport { Text } from '../../typography';\nimport { useDensityConfig, type ComponentScale } from '../../../lib/ui-provider';\nimport { resolveComponentScale } from '../../../lib/ui-provider/scale';\nimport { cn } from '../../../lib/utils';\nimport type { SemanticTone } from '../../../lib/component-vocabulary';\n\nexport type StackedAvatarsSize = ComponentScale;\nexport type StackedAvatarTone = SemanticTone;\n\nexport interface StackedAvatarUser {\n\t/** Stable identity for this entry. */\n\tid?: string;\n\t/** Form field name, forwarded for native submits. */\n\tname: string;\n\timageUrl?: string;\n\t/** Optional semantic tone override for this user's fallback. Numeric values map to the token set. */\n\ttone?: StackedAvatarTone | number;\n}\n\nexport interface StackedAvatarsProps {\n\tusers: StackedAvatarUser[];\n\tmax?: number;\n\t/** Size preset. */\n\tsize?: StackedAvatarsSize;\n\tclassName?: string;\n\t/** Whether to render a `+N` count when `users.length > max`. Default `true`. */\n\tshowOverflow?: boolean;\n\t/** Provide custom overflow text (e.g. \"+12 more\"). Default `+N`. */\n\toverflowFormatter?: (overflow: number) => React.ReactNode;\n\t/** Extra class names applied to each avatar root. */\n\tavatarClassName?: string;\n}\n\nconst FALLBACK_TONES: StackedAvatarTone[] = [\n\t'neutral',\n\t'primary',\n\t'secondary',\n\t'info',\n\t'success',\n];\n\nconst FALLBACK_TONE_CLASSNAMES: Record<StackedAvatarTone, string> = {\n\tneutral: 'bg-muted text-muted-foreground',\n\tprimary: 'bg-primary/10 text-primary-accent',\n\tsecondary: 'bg-secondary text-secondary-foreground',\n\tinfo: 'bg-info/10 text-info',\n\tsuccess: 'bg-success/10 text-success',\n\twarning: 'bg-warning/15 text-warning',\n\tdestructive: 'bg-destructive/10 text-destructive',\n};\n\nfunction pickFallbackTone(seed: string | number, override?: StackedAvatarTone | number) {\n\tif (typeof override === 'string') {\n\t\treturn override;\n\t}\n\tif (typeof override === 'number') {\n\t\treturn FALLBACK_TONES[Math.abs(override) % FALLBACK_TONES.length];\n\t}\n\tconst key = typeof seed === 'number' ? seed : Array.from(seed).reduce((s, c) => s + c.charCodeAt(0), 0);\n\treturn FALLBACK_TONES[key % FALLBACK_TONES.length];\n}\n\nexport function StackedAvatars({\n\tusers,\n\tmax = 4,\n\tsize: sizeProp,\n\tclassName,\n\tshowOverflow = true,\n\toverflowFormatter,\n\tavatarClassName,\n}: StackedAvatarsProps) {\n\tconst { defaultScale } = useDensityConfig();\n\tconst size = resolveComponentScale(sizeProp, defaultScale);\n\tconst visible = users.slice(0, max);\n\tconst overflow = Math.max(0, users.length - max);\n\tconst overflowContent = overflowFormatter ? overflowFormatter(overflow) : `+${overflow}`;\n\n\treturn (\n\t\t<AvatarGroup className={cn('stacked-avatars--component', className)}>\n\t\t\t{visible.map((user, index) => {\n\t\t\t\tconst initials = formatInitials(user.name, {\n\t\t\t\t\tmaxCharacters: size === 'sm' ? 1 : 2,\n\t\t\t\t\tfallback: '?',\n\t\t\t\t});\n\t\t\t\tconst fallbackTone = pickFallbackTone(user.id ?? user.name ?? index, user.tone);\n\t\t\t\treturn (\n\t\t\t\t\t<Avatar\n\t\t\t\t\t\tkey={user.id ?? `${user.name}-${index}`}\n\t\t\t\t\t\tsize={size}\n\t\t\t\t\t\tclassName={cn('ring-background', avatarClassName)}\n\t\t\t\t\t\ttitle={user.name}\n\t\t\t\t\t>\n\t\t\t\t\t\t{user.imageUrl ? (\n\t\t\t\t\t\t\t<AvatarImage src={user.imageUrl} alt={user.name} />\n\t\t\t\t\t\t) : null}\n\t\t\t\t\t\t<AvatarFallback\n\t\t\t\t\t\t\tclassName={cn(\n\t\t\t\t\t\t\t\t'font-semibold',\n\t\t\t\t\t\t\t\tFALLBACK_TONE_CLASSNAMES[fallbackTone],\n\t\t\t\t\t\t\t)}\n\t\t\t\t\t\t>\n\t\t\t\t\t\t\t{initials}\n\t\t\t\t\t\t</AvatarFallback>\n\t\t\t\t\t</Avatar>\n\t\t\t\t);\n\t\t\t})}\n\t\t\t{!!showOverflow && overflow > 0 && (\n\t\t\t\t<AvatarGroupCount>\n\t\t\t\t\t{typeof overflowContent === 'string' || typeof overflowContent === 'number' || typeof overflowContent === 'bigint' ? (\n\t\t\t\t\t\t<Text tag=\"span\" size=\"xs\" weight=\"semibold\">\n\t\t\t\t\t\t\t{overflowContent}\n\t\t\t\t\t\t</Text>\n\t\t\t\t\t) : overflowContent}\n\t\t\t\t</AvatarGroupCount>\n\t\t\t)}\n\t\t</AvatarGroup>\n\t);\n}\n\nStackedAvatars.displayName = 'StackedAvatars';\n"],"mappings":"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"}