@frontify/fondue 13.5.0 → 13.6.0

package/dist/tools/codemod/index.js

@@ -573,6 +573,19 @@ const deprecated = [
   "AccordionHeaderProps",
   "AccordionItem",
   "ActionMenuProps",
+  "AssetInput",
+  "AssetInputMenuBlock",
+  "AssetInputMenuDefaultItemType",
+  "AssetInputMenuItemContentProps",
+  "AssetInputMenuItemContentSize",
+  "AssetInputMenuItemProps",
+  "AssetInputMenuItemStyle",
+  "AssetInputMenuItemType",
+  "AssetInputMenuSwitchItemType",
+  "AssetInputProps",
+  "AssetInputSelectionIndicatorIcon",
+  "AssetInputSize",
+  "AssetType",
   "Breadcrumb",
   "Breadcrumbs",
   "CollapsibleWrap",
@@ -597,9 +610,11 @@ const deprecated = [
   "FormControlStyle",
   "FrontifyPattern",
   "HelperPosition",
+  "ImageAsset",
   "Item",
   "LegacyTextarea",
   "LegacyTextareaProps",
+  "LibrarySource",
   "MenuItem",
   "MenuItemContentSize",
   "MenuItemProps",
@@ -624,6 +639,7 @@ const deprecated = [
   "Toast",
   "ToastAnimationDirection",
   "ToastStyle",
+  "UploadSource",
   "Validation",
   "useCopy",
   "useForwardedRef",

package/dist/tools/internal/index.js

@@ -11,6 +11,19 @@ const deprecated = [
   "AccordionHeaderProps",
   "AccordionItem",
   "ActionMenuProps",
+  "AssetInput",
+  "AssetInputMenuBlock",
+  "AssetInputMenuDefaultItemType",
+  "AssetInputMenuItemContentProps",
+  "AssetInputMenuItemContentSize",
+  "AssetInputMenuItemProps",
+  "AssetInputMenuItemStyle",
+  "AssetInputMenuItemType",
+  "AssetInputMenuSwitchItemType",
+  "AssetInputProps",
+  "AssetInputSelectionIndicatorIcon",
+  "AssetInputSize",
+  "AssetType",
   "Breadcrumb",
   "Breadcrumbs",
   "CollapsibleWrap",
@@ -35,9 +48,11 @@ const deprecated = [
   "FormControlStyle",
   "FrontifyPattern",
   "HelperPosition",
+  "ImageAsset",
   "Item",
   "LegacyTextarea",
   "LegacyTextareaProps",
+  "LibrarySource",
   "MenuItem",
   "MenuItemContentSize",
   "MenuItemProps",
@@ -62,6 +77,7 @@ const deprecated = [
   "Toast",
   "ToastAnimationDirection",
   "ToastStyle",
+  "UploadSource",
   "Validation",
   "useCopy",
   "useForwardedRef",
@@ -69,19 +85,6 @@ const deprecated = [
   "useMobileDetection"
 ];
 const active = [
-  "AssetInput",
-  "AssetInputMenuBlock",
-  "AssetInputMenuDefaultItemType",
-  "AssetInputMenuItemContentProps",
-  "AssetInputMenuItemContentSize",
-  "AssetInputMenuItemProps",
-  "AssetInputMenuItemStyle",
-  "AssetInputMenuItemType",
-  "AssetInputMenuSwitchItemType",
-  "AssetInputProps",
-  "AssetInputSelectionIndicatorIcon",
-  "AssetInputSize",
-  "AssetType",
   "CollapsibleWrap",
   "CollisionPosition",
   "DragHandle",
@@ -92,12 +95,10 @@ const active = [
   "ExpandButtonProps",
   "FilterableMultiSelect",
   "INDENTATION_WIDTH",
-  "ImageAsset",
   "InputLabelProps",
   "InternalTreeItemMultiSelectProps",
   "InternalTreeItemProps",
   "LegacyTextarea",
-  "LibrarySource",
   "MultiSelect",
   "OnExpandCallback",
   "OnSelectCallback",
@@ -144,7 +145,6 @@ const active = [
   "TreeProps",
   "TreeState",
   "TreeStateAction",
-  "UploadSource",
   "addSelectedIds",
   "addSelectedItemsFromSelection",
   "cleanOrphanSelectedIds",

package/dist/tools/sdk-cli/adapters/claude-skill/skill/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: fondue
+description: Queries the locally installed `@frontify/fondue/sdk` to surface accurate Fondue component metadata. ALWAYS use when picking a Fondue component (button, dialog, dropdown, tabs, …), finding a design token or utility class, or setting up the `@frontify/fondue` package.
+allowed-tools: Bash(node *)
+---
+
+# Fondue
+
+Use `@frontify/fondue/sdk` as the source of truth for every Fondue question. Never invent component names, props, token ids, or imports from memory — query the SDK.
+
+**Runs against the project's locally installed Fondue.** Invoke `node` from the project root (or a subdirectory) so `@frontify/fondue` resolves from `node_modules` — results reflect the exact version this project depends on, not the version the skill was authored against.
+
+## Verify the SDK is available
+
+```bash
+node -e "import('@frontify/fondue/sdk').then((m) => console.log(JSON.stringify({ components: m.components.size, tokens: m.tokens.size, guides: m.guides.size })))"
+```
+
+If that errors with `Cannot find package`, the project hasn't installed Fondue yet:
+
+```bash
+pnpm add @frontify/fondue   # or npm i / yarn add
+```
+
+## How to query
+
+The SDK is a synchronous, zero-I/O ES module that resolves from the user's project. Three singletons share the same query surface:
+
+```ts
+import { components, tokens, guides } from '@frontify/fondue/sdk';
+
+// Same shape on each domain:
+components.list();
+components.get('Button');             // ComponentNode | undefined (never throws)
+components.has('Button');             // boolean
+components.where({ text: 'dropdown' });
+components.size;                      // number
+```
+
+`where(filter)` clauses AND-combine; array-valued clauses OR within the clause. `get` and `where` never throw; missing ids return `undefined` / `[]`.
+
+Nodes have **scalar fields** (read as properties) and **graph edges** (call as methods):
+
+```ts
+const button = components.get('Button');
+button?.importStatement;              // scalar
+button?.props;                        // scalar (array)
+button?.category();                   // edge → ComponentFacetNode { name, list, where, … }
+button?.related();                    // edge → ComponentNode[]
+```
+
+### Running queries from Claude
+
+For one-liners, use `node -e`:
+
+```bash
+node -e "import('@frontify/fondue/sdk').then(({components}) => console.log(JSON.stringify(components.where({text:'dropdown'}).map((c)=>({name:c.name,import:c.importStatement,canonical:c.examples.find((e)=>e.isCanonical)?.code})))))"
+```
+
+For anything multi-line, pipe a module via stdin to avoid quoting hell:
+
+```bash
+node --input-type=module <<'EOF'
+import { components } from '@frontify/fondue/sdk';
+const candidates = components.where({ text: 'dropdown', status: 'released' }).slice(0, 5);
+console.log(JSON.stringify(candidates.map((c) => ({
+    name: c.name,
+    category: c.category().name,
+    tags: c.tags().map((t) => t.name),
+    import: c.importStatement,
+    canonical: c.examples.find((e) => e.isCanonical)?.code ?? c.examples[0]?.code ?? null,
+})), null, 2));
+EOF
+```
+
+Always emit `JSON.stringify(...)` so the response is parseable. Never `console.log(node)` directly — facet methods serialize as `[Function]`.
+
+For the formal contract (every filter clause, node shape, facet method), see [`reference.md`](./reference.md).
+
+---
+
+## Workflow 1 — Setting up Fondue
+
+Read the canonical setup prose from the SDK rather than paraphrasing — the steps change between releases (font URLs, package layout, theme provider API).
+
+```bash
+node -e "import('@frontify/fondue/sdk').then(({guides}) => console.log(guides.get('getting-started')?.content))"
+```
+
+For upgrades:
+
+```bash
+node -e "import('@frontify/fondue/sdk').then(({guides}) => console.log(guides.get('upgrading')?.content))"
+```
+
+To discover other bundled guides:
+
+```bash
+node -e "import('@frontify/fondue/sdk').then(({guides}) => console.log(JSON.stringify(guides.list().map((g)=>({id:g.id,title:g.title})))))"
+```
+
+The output is the same markdown the Storybook docs render. Use it as the source for token imports, component-style imports, font face definitions, the Tailwind preset, `ThemeProvider`.
+
+## Workflow 2 — Finding a component
+
+Start with intent-based search:
+
+```bash
+node --input-type=module <<'EOF'
+import { components } from '@frontify/fondue/sdk';
+console.log(JSON.stringify(components.where({ text: 'dropdown' }).map((c) => ({
+    name: c.name,
+    category: c.category().name,
+    status: c.status,
+    description: c.description,
+})), null, 2));
+EOF
+```
+
+Narrow by category or tag when the use case maps cleanly:
+
+```ts
+components.where({ category: 'overlay', status: 'released' });
+components.where({ tag: 'cta' });
+components.where({ category: 'input', tag: 'cta' });
+```
+
+Once you have a candidate, pull the recommendation shape:
+
+```bash
+node --input-type=module <<'EOF'
+import { components } from '@frontify/fondue/sdk';
+const c = components.get('Button');
+console.log(JSON.stringify({
+    name: c.name,
+    description: c.description,
+    importStatement: c.importStatement,
+    canonical: c.examples.find((e) => e.isCanonical)?.code ?? c.examples[0]?.code,
+    requiredProps: c.props.filter((p) => p.required).map((p) => p.name),
+    subComponents: c.subComponents.map((sc) => sc.name),
+    related: c.related().map((r) => r.name),
+    instructions: c.instructions,
+}, null, 2));
+EOF
+```
+
+**Recommendation shape** — when you suggest a component, output: the name, what it's for, the import statement, and the canonical example. If the use case isn't a clean match, list 2–3 candidates with their categories and let the user pick.
+
+**Icons** live in the components graph under `category: 'icon'`. They have empty `status`, empty `props`, empty `related()` — don't probe those fields. Find them with:
+
+```ts
+components.where({ category: 'icon', tag: 'arrow' });
+components.get('IconAdobeCreativeCloud')?.importStatement;
+```
+
+When nothing matches:
+- Try a related tag — `components.tags().map((t) => t.name)` lists every tag.
+- Look at the closest hit's `related()`.
+- If there truly is no component for the use case, say so. Don't recommend hand-rolling something Fondue already provides, but don't invent a component name either.
+
+## Workflow 3 — Picking tokens for a custom component
+
+Two layers exist:
+
+- `tokens` — atomic design tokens (colors, sizes, shadows, strings). Each has a CSS variable and a Tailwind class.
+- `tokens.utilities` — composed Tailwind utilities (typography classes like `tw-body-large-strong`) bundling multiple token references.
+
+```ts
+tokens.where({ text: 'primary' });
+tokens.where({ category: 'colors', themeable: true });
+tokens.where({ keyPathStartsWith: 'colors.text' });
+tokens.type('color')?.where({ themeable: true });
+
+const t = tokens.get('color-text-weak');
+t?.value;              // 'var(--color-text-weak)'
+t?.cssVariable;        // '--color-text-weak'
+t?.tailwindClass;      // 'tw-text-weak'
+t?.themeable;          // true
+
+// Typography: always use the utility class, not raw font tokens
+tokens.utilities.where({ keyPathStartsWith: 'utilities.text' });
+```
+
+Rules:
+- Prefer `themeable: true` tokens for any user-facing surface so dark mode and theming work out of the box.
+- Prefer the Tailwind class when the project uses `@frontify/fondue/tokens/tailwind`; prefer the CSS variable otherwise.
+- For typography, recommend the **utility class** — not raw font-size / line-height / weight tokens.
+- Never invent token ids. If `tokens.get(id)` returns `undefined`, search again.
+- If the design calls for a value with no matching token, surface that explicitly — don't silently hardcode. The right answer is usually a token the user didn't know existed.
+
+---
+
+## Common pitfalls
+
+| Mistake | Fix |
+| ------- | --- |
+| Calling `.where()` / `.get()` on the array returned by `list()` / `where()` | Arrays are arrays. Use native `.filter` / `.find`, or navigate back to a facet to query. |
+| Assuming a component exists ("there must be a `Combobox`") | `components.has('Combobox')` first, or `components.where({ text: 'combobox' })` |
+| Hardcoding a hex / px value in custom code | `tokens.where({ text: '<intent>' })` — most "obvious" values have a token |
+| Treating icons like normal components, reading `status` / `props` | Detect with `node.category().name === 'icon'`. Icons have empty `status`, `props`, `related`. |
+| Importing `Button` from the wrong path | `components.get('Button')?.importStatement` is authoritative |
+| Suggesting setup steps from memory | `guides.get('getting-started')?.content` — always the live text |
+| `console.log(node)` instead of `JSON.stringify` | Facet methods serialize as `[Function]`; always stringify before logging |
+
+## Going deeper
+
+[`reference.md`](./reference.md) is the formal contract: every export, every filter clause per domain, every node and facet type, error semantics. Load it when you need to verify a filter clause is valid (`ComponentFilter`, `TokenFilter`, `GuideFilter`) or that a method exists. Prefer it over web lookups or upstream GitHub.

package/dist/tools/sdk-cli/adapters/claude-skill/skill/reference.md

@@ -0,0 +1,235 @@
+## Contents
+
+- [Exports](#exports) — the three singletons and the shared `QueryApi` shape
+- [Components](#components) — `ComponentFilter`, `ComponentNode`, icons
+- [Tokens](#tokens) — `TokenFilter`, `TokenNode`, utilities
+- [Guides](#guides) — guide ids and shape
+- [Facets](#facets) — `FacetNode` shape and how to reach them
+- [Error semantics](#error-semantics) — what throws, what returns `undefined`
+- [Runtime guarantees](#runtime-guarantees) — module type, Node version, deps
+
+## Exports
+
+```ts
+import { components, tokens, guides } from '@frontify/fondue/sdk';
+```
+
+Three singletons. Each has the same query surface; each returns its own node types.
+
+```ts
+interface QueryApi<Node, Filter> {
+    list(): readonly Node[];
+    get(id: string): Node | undefined; // never throws; returns undefined for unknown ids
+    has(id: string): boolean;
+    where(filter: Filter): readonly Node[]; // AND-combined; array-valued clauses OR within
+    readonly size: number;
+}
+```
+
+Plain arrays returned from `list()` / `where()` / `node.related()` are arrays — they don't carry the query surface. Use native `.filter` / `.find`, or navigate back to a facet to re-query.
+
+## Components
+
+```ts
+components: QueryApi<ComponentNode, ComponentFilter> & {
+    categories(): readonly ComponentFacetNode[];
+    category(name: string): ComponentFacetNode | undefined;
+    tags(): readonly ComponentFacetNode[];
+    tag(name: string): ComponentFacetNode | undefined;
+};
+```
+
+### `ComponentFilter`
+
+| Clause     | Type                          | Notes                                                               |
+| ---------- | ----------------------------- | ------------------------------------------------------------------- |
+| `category` | `string \| readonly string[]` | OR within array                                                     |
+| `status`   | `string \| readonly string[]` | OR within array                                                     |
+| `tag`      | `string \| readonly string[]` | Matches if component carries any tag in the array                   |
+| `text`     | `string`                      | Case-insensitive substring across name, description, category, tags |
+
+All clauses AND-combine.
+
+### `ComponentNode`
+
+```ts
+interface ComponentNode {
+    // scalar fields
+    name: string;
+    description: string;
+    status: string; // '' for icons
+    importStatement: string;
+    instructions: string; // hand-written usage notes, often empty
+    props: readonly ComponentProp[];
+    subComponents: readonly ComponentSubComponent[];
+    examples: readonly ComponentExample[];
+    typeDefinitions: Readonly<Record<string, string>>;
+
+    // graph edges (methods)
+    category(): ComponentFacetNode; // throws on data inconsistency only
+    tags(): readonly ComponentFacetNode[];
+    related(): readonly ComponentNode[]; // unknown names silently skipped
+    toJSON(): ComponentDetails;
+}
+
+interface ComponentProp {
+    name: string;
+    type: string;
+    required: boolean;
+    defaultValue: string | null;
+    description: string;
+    deprecated: boolean;
+    deprecationMessage: string;
+}
+
+interface ComponentExample {
+    name: string;
+    description: string;
+    code: string;
+    isCanonical: boolean; // there is at most one canonical example per component
+}
+
+interface ComponentSubComponent {
+    name: string; // e.g. 'Dialog.Header'
+    props: readonly ComponentProp[];
+}
+```
+
+### Icons
+
+Icons are components with `category: 'icon'`. They have:
+
+- empty `status`, empty `props`, empty `related()`, empty `subComponents`
+- a non-empty `importStatement` (e.g. `import { IconAdobeCreativeCloud } from '@frontify/fondue/icons';`)
+- tags (e.g. `'arrow'`, `'brand'`)
+
+Filter to icons with `components.where({ category: 'icon' })`. Detect at the node with `node.category().name === 'icon'`.
+
+## Tokens
+
+```ts
+tokens: QueryApi<TokenNode, TokenFilter> & {
+    categories(): readonly TokenFacetNode[];
+    category(name: string): TokenFacetNode | undefined;
+    types(): readonly TokenFacetNode[];
+    type(name: TokenValueType): TokenFacetNode | undefined;
+    utilities: TokenUtilitiesApi;
+};
+
+type TokenValueType = 'color' | 'float' | 'shadow' | 'string';
+```
+
+### `TokenFilter`
+
+| Clause              | Type                                          | Notes                                               |
+| ------------------- | --------------------------------------------- | --------------------------------------------------- |
+| `category`          | `string \| readonly string[]`                 | e.g. `'colors'`, `'sizes'`                          |
+| `type`              | `TokenValueType \| readonly TokenValueType[]` |                                                     |
+| `themeable`         | `boolean`                                     |                                                     |
+| `keyPathStartsWith` | `string`                                      | Dot-joined keyPath prefix, e.g. `'colors.charts'`   |
+| `text`              | `string`                                      | Case-insensitive against id, tailwindClass, keyPath |
+
+### `TokenNode`
+
+```ts
+interface TokenNode {
+    id: string; // e.g. 'color-charts-primary-default'
+    value: string; // often `var(--token)` or a literal
+    cssVariable: string; // 'var(--color-charts-primary-default)'
+    tailwindClass: string; // e.g. '*-charts-primary'
+    themeable: boolean;
+    keyPath: readonly string[]; // ['colors','charts','primary','default']
+
+    category(): TokenFacetNode;
+    type(): TokenFacetNode;
+    toJSON(): Token;
+}
+```
+
+### Utilities
+
+```ts
+tokens.utilities: QueryApi<TokenUtilityNode, TokenUtilityFilter> & {
+    classes(): readonly string[];
+};
+```
+
+No `categories()` / `types()` on utilities — they're a leaf domain.
+
+```ts
+interface TokenUtilityFilter {
+    themeable?: boolean;
+    keyPathStartsWith?: string; // typography utilities live under 'utilities.text'
+    text?: string;
+}
+
+interface TokenUtilityNode {
+    id: string;
+    tailwindClass: string; // e.g. 'tw-body-large-strong'
+    themeable: boolean;
+    keyPath: readonly string[];
+    properties: readonly TokenUtilityProperty[];
+}
+
+interface TokenUtilityProperty {
+    id: string;
+    type: TokenValueType;
+    value: string;
+    cssVariable: string;
+}
+```
+
+## Guides
+
+```ts
+guides: QueryApi<Guide, GuideFilter>;
+
+interface Guide {
+    id: string; // slug from filename, e.g. 'getting-started'
+    title: string; // extracted from the first `# Title` line
+    content: string; // raw markdown body, includes the leading `# Title`
+}
+
+interface GuideFilter {
+    text?: string; // case-insensitive against id, title, content
+}
+```
+
+Known ids include `getting-started`, `contributing`, `upgrading`. The bundled set may grow; call `guides.list()` to see the current corpus.
+
+## Facets
+
+`ComponentFacetNode` and `TokenFacetNode` share this shape:
+
+```ts
+interface FacetNode<Node, Filter> {
+    name: string;
+    list(): readonly Node[];
+    get(id: string): Node | undefined;
+    has(id: string): boolean;
+    where(filter: Filter): readonly Node[];
+    size: number;
+}
+```
+
+Reach a facet via the domain's accessor or via a node's edge:
+
+```ts
+components.category('input'); // facet
+components.tag('cta'); // facet
+components.get('Button')?.category(); // facet from a node
+tokens.category('colors')?.where({ themeable: true });
+```
+
+## Error semantics
+
+- `get(id)` never throws — returns `undefined` for unknown ids.
+- `node.related()` silently skips unknown names.
+- `node.category()` throws only on internal data inconsistency (a component referencing a category that doesn't exist) — treat as a bug to report, not a runtime case to handle.
+- `where(filter)` with an empty filter returns every node in the domain.
+
+## Runtime guarantees
+
+- Synchronous, zero file I/O.
+- Pure ES module; Node 18+.
+- No peer dependencies, no React, no DOM.