@particle-academy/react-fancy 6.2.0 → 6.4.0

package/dist/sidebar.js

@@ -6,8 +6,8 @@ import './chunk-CPY7NHXM.js';
 import './chunk-ZQ3VXRUY.js';
 import './chunk-5U2DZ7AV.js';
 import './chunk-3K2CEAI7.js';
-import './chunk-MQ6VGG62.js';
 import './chunk-5VMILVWD.js';
+import './chunk-MQ6VGG62.js';
 import './chunk-RBCMKPBX.js';
 import './chunk-S53A6JIE.js';
 import './chunk-RGANGU7X.js';

package/dist/stepper.cjs

@@ -0,0 +1,14 @@
+'use strict';
+
+var chunkY3QAEF2P_cjs = require('./chunk-Y3QAEF2P.cjs');
+require('./chunk-SNHU2AI4.cjs');
+require('./chunk-ZU5Q77OT.cjs');
+
+
+
+Object.defineProperty(exports, "Stepper", {
+  enumerable: true,
+  get: function () { return chunkY3QAEF2P_cjs.Stepper; }
+});
+//# sourceMappingURL=stepper.cjs.map
+//# sourceMappingURL=stepper.cjs.map

package/dist/stepper.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"stepper.cjs"}

package/dist/stepper.d.cts

@@ -0,0 +1,72 @@
+import * as react from 'react';
+import { OlHTMLAttributes, ReactNode } from 'react';
+
+/**
+ * Where a step stands. `upcoming`, `current` and `complete` are derived from
+ * the step's position against `current`; `error` is only ever declared, on the
+ * step itself, and overrides the derived state.
+ */
+type StepperStepState = "upcoming" | "current" | "complete" | "error";
+type StepperOrientation = "vertical" | "horizontal";
+/** One step, as data. Everything an agent needs to emit a stepper is JSON. */
+interface StepperStep$1 {
+    /** Stable identity, rendered as `data-step-id`. Recommended for agent handles. */
+    id?: string;
+    /** Step heading. */
+    title: ReactNode;
+    /** Short supporting line under the title. */
+    description?: ReactNode;
+    /** The step's body: instructions, a code sample, a screenshot. */
+    content?: ReactNode;
+    /**
+     * Override the derived state. Usually `"error"`; the others are accepted so
+     * a caller can mark a skipped step complete without moving `current`.
+     */
+    state?: StepperStepState;
+    /** With `clickable`, renders this step's button disabled. */
+    disabled?: boolean;
+}
+interface StepperProps extends Omit<OlHTMLAttributes<HTMLOListElement>, "onChange" | "children" | "defaultValue"> {
+    /** The steps as data. Wins over `children` when both are given. */
+    steps?: StepperStep$1[];
+    /** `Stepper.Step` elements, read as data. Ignored when `steps` is given. */
+    children?: ReactNode;
+    /** Controlled index of the current step. `steps.length` means all complete. */
+    current?: number;
+    /** Uncontrolled starting index. Default `0`. */
+    defaultCurrent?: number;
+    /** Called with the chosen step's index. Only fires when `clickable`. */
+    onChange?: (index: number) => void;
+    /** Default `"vertical"`. Horizontal suits short content. */
+    orientation?: StepperOrientation;
+    /**
+     * Render each step's header as a button that makes it current. Off by
+     * default: a Stepper is content, with no interactive elements at all.
+     */
+    clickable?: boolean;
+    /** Show every step's content (default), or only the current step's. */
+    showContent?: "all" | "current";
+    /** Words for each state, read by screen readers. English by default. */
+    stateLabels?: Partial<Record<StepperStepState, string>>;
+}
+/** Declarative form of a `StepperStep`; its children are the step's content. */
+interface StepperStepProps extends Omit<StepperStep$1, "content"> {
+    children?: ReactNode;
+}
+
+/**
+ * Declarative step. Renders nothing itself: `Stepper` reads its props as data
+ * and renders it through the same path as an entry in `steps`, so the two forms
+ * cannot drift apart in markup, states or handles. Its children are the step's
+ * content. It must be a DIRECT child of `Stepper` (not wrapped in another
+ * component) for the same reason `Breadcrumbs.Item` must.
+ */
+declare function StepperStep(_props: StepperStepProps): null;
+declare namespace StepperStep {
+    var displayName: string;
+}
+declare const Stepper: react.ForwardRefExoticComponent<StepperProps & react.RefAttributes<HTMLOListElement>> & {
+    Step: typeof StepperStep;
+};
+
+export { Stepper, type StepperOrientation, type StepperProps, type StepperStep$1 as StepperStep, type StepperStepProps, type StepperStepState };

package/dist/stepper.d.ts

@@ -0,0 +1,72 @@
+import * as react from 'react';
+import { OlHTMLAttributes, ReactNode } from 'react';
+
+/**
+ * Where a step stands. `upcoming`, `current` and `complete` are derived from
+ * the step's position against `current`; `error` is only ever declared, on the
+ * step itself, and overrides the derived state.
+ */
+type StepperStepState = "upcoming" | "current" | "complete" | "error";
+type StepperOrientation = "vertical" | "horizontal";
+/** One step, as data. Everything an agent needs to emit a stepper is JSON. */
+interface StepperStep$1 {
+    /** Stable identity, rendered as `data-step-id`. Recommended for agent handles. */
+    id?: string;
+    /** Step heading. */
+    title: ReactNode;
+    /** Short supporting line under the title. */
+    description?: ReactNode;
+    /** The step's body: instructions, a code sample, a screenshot. */
+    content?: ReactNode;
+    /**
+     * Override the derived state. Usually `"error"`; the others are accepted so
+     * a caller can mark a skipped step complete without moving `current`.
+     */
+    state?: StepperStepState;
+    /** With `clickable`, renders this step's button disabled. */
+    disabled?: boolean;
+}
+interface StepperProps extends Omit<OlHTMLAttributes<HTMLOListElement>, "onChange" | "children" | "defaultValue"> {
+    /** The steps as data. Wins over `children` when both are given. */
+    steps?: StepperStep$1[];
+    /** `Stepper.Step` elements, read as data. Ignored when `steps` is given. */
+    children?: ReactNode;
+    /** Controlled index of the current step. `steps.length` means all complete. */
+    current?: number;
+    /** Uncontrolled starting index. Default `0`. */
+    defaultCurrent?: number;
+    /** Called with the chosen step's index. Only fires when `clickable`. */
+    onChange?: (index: number) => void;
+    /** Default `"vertical"`. Horizontal suits short content. */
+    orientation?: StepperOrientation;
+    /**
+     * Render each step's header as a button that makes it current. Off by
+     * default: a Stepper is content, with no interactive elements at all.
+     */
+    clickable?: boolean;
+    /** Show every step's content (default), or only the current step's. */
+    showContent?: "all" | "current";
+    /** Words for each state, read by screen readers. English by default. */
+    stateLabels?: Partial<Record<StepperStepState, string>>;
+}
+/** Declarative form of a `StepperStep`; its children are the step's content. */
+interface StepperStepProps extends Omit<StepperStep$1, "content"> {
+    children?: ReactNode;
+}
+
+/**
+ * Declarative step. Renders nothing itself: `Stepper` reads its props as data
+ * and renders it through the same path as an entry in `steps`, so the two forms
+ * cannot drift apart in markup, states or handles. Its children are the step's
+ * content. It must be a DIRECT child of `Stepper` (not wrapped in another
+ * component) for the same reason `Breadcrumbs.Item` must.
+ */
+declare function StepperStep(_props: StepperStepProps): null;
+declare namespace StepperStep {
+    var displayName: string;
+}
+declare const Stepper: react.ForwardRefExoticComponent<StepperProps & react.RefAttributes<HTMLOListElement>> & {
+    Step: typeof StepperStep;
+};
+
+export { Stepper, type StepperOrientation, type StepperProps, type StepperStep$1 as StepperStep, type StepperStepProps, type StepperStepState };

package/dist/stepper.js

@@ -0,0 +1,5 @@
+export { Stepper } from './chunk-5EW47IH7.js';
+import './chunk-EDYAXGUM.js';
+import './chunk-MMW2JGKZ.js';
+//# sourceMappingURL=stepper.js.map
+//# sourceMappingURL=stepper.js.map

package/dist/stepper.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"stepper.js"}

package/dist/tooltip.cjs

@@ -2,8 +2,8 @@
 
 var chunkOASSZI6M_cjs = require('./chunk-OASSZI6M.cjs');
 require('./chunk-I27K6NLX.cjs');
-require('./chunk-J2DI6RMR.cjs');
 require('./chunk-MKHYENKR.cjs');
+require('./chunk-J2DI6RMR.cjs');
 require('./chunk-TI7D4QDM.cjs');
 require('./chunk-OUYC6EIL.cjs');
 require('./chunk-ZU5Q77OT.cjs');

package/dist/tooltip.js

@@ -1,7 +1,7 @@
 export { Tooltip } from './chunk-GR2WKBER.js';
 import './chunk-SV5BW3IA.js';
-import './chunk-MQ6VGG62.js';
 import './chunk-5VMILVWD.js';
+import './chunk-MQ6VGG62.js';
 import './chunk-RBCMKPBX.js';
 import './chunk-YX6FTJ6N.js';
 import './chunk-MMW2JGKZ.js';

package/docs/Breadcrumbs.md

@@ -34,8 +34,17 @@ import { Breadcrumbs } from "@particle-academy/react-fancy";
 |------|------|---------|-------------|
 | children | `ReactNode` | - | Item label |
 | href | `string` | - | Link URL (renders an anchor when provided) |
-| active | `boolean` | - | Mark as the current page (no link) |
+| as | `ElementType` | - | Link component to render instead of `<a>`, e.g. a router's `<Link>` |
+| onClick | `() => void` | - | Navigate by callback; renders a `<button>` when there is no `href` |
+| active | `boolean` | - | Mark as the current page (no link, `aria-current="page"`) |
 | className | `string` | - | Additional CSS classes |
+| ...HTML attributes | `HTMLAttributes<HTMLElement>` | - | `title`, `id`, `aria-*`, `style`, handlers: forwarded to the crumb's element. Only `title` is also carried into the mobile dropdown |
+
+```tsx
+<Breadcrumbs.Item href="/projects/42" title="Quarterly planning for the platform team">
+  Quarterly planning…
+</Breadcrumbs.Item>
+```
 
 ## Shrinkable Breadcrumbs
 

package/docs/CodeBlock.md

@@ -0,0 +1,84 @@
+# CodeBlock
+
+A display-only code block: `<pre><code>`, syntax-highlighted where a grammar exists, with an optional copy button. Use it for install commands, config snippets and setup instructions.
+
+It contains **no `textarea`, `input`, `select` or `contenteditable` element**, with or without the copy button, so it is safe on pages that must never accept input (for example a provider-setup page that must not accept credentials). The only interactive element is the copy `<button>`, and `copyable={false}` removes that too.
+
+For an editable source surface use [`CodeView`](./CodeView.md); for a full multi-language editor use `@particle-academy/fancy-code`'s `CodeEditor`.
+
+## Import
+
+```tsx
+import { CodeBlock } from "@particle-academy/react-fancy";
+// or, just this component:
+import { CodeBlock } from "@particle-academy/react-fancy/code-block";
+```
+
+## Basic Usage
+
+```tsx
+<CodeBlock code="npm install @particle-academy/react-fancy" language="bash" />
+```
+
+## With a filename header and line numbers
+
+```tsx
+<CodeBlock
+  title=".env"
+  language="env"
+  showLineNumbers
+  code={"OPENAI_API_KEY=your-key-here\nOPENAI_ORG=org-id"}
+/>
+```
+
+With `title`, the copy button sits in the header with a visible "Copy" label. Without it, the button floats in the top-right corner of the code, icon-only until it shows its feedback.
+
+## Highlighting
+
+Only **HTML** is highlighted (`language` of `"html"`, `"htm"`, `"xml"` or `"xhtml"`). It is the one grammar `@particle-academy/fancy-file-commons` ships. **Every other language, including `bash`, `json`, `env`, `php`, `typescript` and `python`, renders as plain, un-highlighted text** in the same font, size and palette. Unknown languages fall back the same way, and nothing throws. `language` is still reflected as `data-language`, so a page can style or target blocks by language today.
+
+## Props
+
+Also accepts every `<div>` attribute (`id`, `aria-label`, `style`, `data-*`, ...), forwarded to the root element.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| code | `string` | - | The source to show. Rendered as text, never parsed as HTML |
+| language | `string` | `"plaintext"` | Language id. Only HTML aliases are highlighted; everything else is plain text |
+| copyable | `boolean` | `true` | Show the copy button |
+| title | `ReactNode` | - | Header above the code (a filename, or a label like "Terminal") |
+| showLineNumbers | `boolean` | `false` | Number each line in a gutter that is not part of the code text |
+| wrap | `boolean` | `false` | Wrap long lines instead of scrolling horizontally |
+| copyLabels | `{ copy?, copied?, failed? }` | `"Copy code"`, `"Copied"`, `"Copy failed"` | Words on the copy button, for translation |
+| onCopyCode | `(event: { text: string; ok: boolean }) => void` | - | Called after every copy attempt |
+| className | `string` | - | Additional CSS classes on the root element |
+
+## Copying
+
+The button copies **exactly the `code` prop**: no highlight markup, no line numbers, no header text. It uses `navigator.clipboard.writeText`. When the Clipboard API is missing (server, insecure `http:` context, old browser) or the write is refused, nothing throws: the button shows "Copy failed" for two seconds, and `onCopyCode` receives `ok: false`. A successful copy shows "Copied" visibly, in the button's accessible name, and in a polite live region.
+
+## Theming
+
+The same palette as `CodeView` (`LIGHT_COLORS` / `DARK_COLORS` from `fancy-file-commons`), so the two sit together. Dark is chosen when `<html>` has the `dark` class or the OS prefers dark. On the server, and during hydration, the light palette is used, then the real theme.
+
+## Security
+
+Code is escaped before it reaches `dangerouslySetInnerHTML`: `highlightCode` escapes `&`, `<` and `>` in every slice it emits, highlighted or plain, and token colours pass an allow-list. `<script>` in `code` renders as the text `<script>`.
+
+## Server rendering
+
+No `window`, `document` or `navigator` access during render. Tested with `renderToString` with all three undefined.
+
+## Agent handles
+
+| Attribute | On | Value |
+|-----------|----|-------|
+| `data-react-fancy-code-block` | root `<div>` | - |
+| `data-language` | root | the `language` prop |
+| `data-wrap` | root | `true` / `false` |
+| `data-react-fancy-code-block-header` / `-title` | the header and its title | only with `title` |
+| `data-react-fancy-code-block-pre` / `-code` | the `<pre>` / `<code>` | - |
+| `data-react-fancy-code-block-copy` | the copy `<button>` | - |
+| `data-copy-state` | the copy `<button>` | `idle` / `copied` / `failed` |
+| `data-react-fancy-code-block-line` | each line, with `showLineNumbers` | the line number |
+| `data-react-fancy-code-block-line-number` / `-line-content` | each line's gutter / text | - |

package/docs/Stepper.md

@@ -0,0 +1,124 @@
+# Stepper
+
+An ordered list of steps, each with a title, an optional description and rich content, and a state: `upcoming`, `current`, `complete` or `error`. Use it for setup walkthroughs and multi-step guides. Data-driven (via the `steps` prop) or compound (`Stepper.Step`).
+
+By default a Stepper is **pure content**: an `<ol>` with no buttons, inputs or form elements, so it is safe on pages that forbid interactive controls. Clickable steps are opt-in with `clickable`.
+
+For in-app product tours, use `fancy-walkthrough`. For a record of past events, use `Timeline`.
+
+## Import
+
+```tsx
+import { Stepper } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Stepper
+  aria-label="Connect your provider"
+  defaultCurrent={1}
+  steps={[
+    { id: "account", title: "Create an account", description: "At the provider", content: <p>Sign up at the provider's site.</p> },
+    { id: "key", title: "Copy the API key", content: <p>Open Settings, then API keys.</p> },
+    { id: "paste", title: "Paste it here", content: <p>Come back to this page.</p> },
+  ]}
+/>
+```
+
+Steps before `current` are `complete`, the step at `current` is `current`, and steps after it are `upcoming`. A step's own `state` overrides that, which is how a step shows `error`.
+
+## Stepper Props
+
+Also accepts every `<ol>` attribute (`id`, `aria-label`, `style`, `data-*`, ...), forwarded to the list.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| steps | `StepperStep[]` | - | The steps as data. Wins over `children` when both are given |
+| children | `ReactNode` | - | `Stepper.Step` elements (direct children only) |
+| current | `number` | - | Controlled index of the current step. `steps.length` means every step is complete |
+| defaultCurrent | `number` | `0` | Uncontrolled starting index |
+| onChange | `(index: number) => void` | - | Called with the chosen step's index. Only fires when `clickable` |
+| orientation | `"vertical" \| "horizontal"` | `"vertical"` | Layout. Horizontal suits short content |
+| clickable | `boolean` | `false` | Render each step's header as a `<button>` that makes it current |
+| showContent | `"all" \| "current"` | `"all"` | Show every step's content, or only the current step's |
+| stateLabels | `Partial<Record<StepperStepState, string>>` | English | Words for each state, read by screen readers |
+| className | `string` | - | Additional CSS classes on the `<ol>` |
+
+## StepperStep (data-driven)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| title | `ReactNode` | yes | Step heading |
+| id | `string` | no | Stable identity, rendered as `data-step-id` |
+| description | `ReactNode` | no | Short line under the title |
+| content | `ReactNode` | no | The step's body |
+| state | `"upcoming" \| "current" \| "complete" \| "error"` | no | Overrides the state derived from `current` |
+| disabled | `boolean` | no | With `clickable`, the step's button is disabled |
+
+## Stepper.Step Props
+
+The same fields as `StepperStep`, with the step's content as `children`. `Stepper.Step` renders nothing by itself: `Stepper` reads it as data, so both forms produce identical markup.
+
+```tsx
+<Stepper current={step} aria-label="Connect your provider">
+  <Stepper.Step title="Create an account" description="At the provider">
+    <p>Sign up at the provider's site.</p>
+  </Stepper.Step>
+  <Stepper.Step title="Copy the API key" state={keyRejected ? "error" : undefined}>
+    <p>Open Settings, then API keys.</p>
+  </Stepper.Step>
+  <Stepper.Step title="Paste it here" />
+</Stepper>
+```
+
+## Clickable steps
+
+```tsx
+const [step, setStep] = useState(0);
+
+<Stepper
+  clickable
+  current={step}
+  onChange={setStep}
+  steps={[
+    { title: "Account" },
+    { title: "API key" },
+    { title: "Finish", disabled: step < 1 },
+  ]}
+/>
+```
+
+With `clickable`, each step's indicator and title become a `type="button"`. The description and content stay outside the button, so links in them remain links. Enter and Space activate a button natively; the arrow keys (Up/Down, or Left/Right when horizontal) and Home/End move focus between enabled steps without changing the current step. Every button stays in the tab order. Clicking the step that is already current does not call `onChange`.
+
+## Horizontal
+
+```tsx
+<Stepper orientation="horizontal" current={1} steps={[{ title: "Cart" }, { title: "Shipping" }, { title: "Pay" }]} />
+```
+
+## Content visibility
+
+`showContent="current"` renders only the current step's content, for a wizard-style view. The default, `"all"`, renders every step's content, for a walkthrough read top to bottom.
+
+## Accessibility
+
+- An `<ol>` of `<li>`s. Give the list an `aria-label`.
+- The current step's `<li>` carries `aria-current="step"`.
+- Each step's state is in text (visually hidden, before the title: "Completed: Create an account"), and the indicator's glyph differs per state (number, tick, "!"), so state never depends on colour alone. Translate the words with `stateLabels`.
+- Server-renders with no `window` or `document` access.
+
+## Agent handles
+
+| Attribute | On | Value |
+|-----------|----|-------|
+| `data-react-fancy-stepper` | `<ol>` | - |
+| `data-orientation` | `<ol>` | `vertical` / `horizontal` |
+| `data-current` | `<ol>` | current index |
+| `data-react-fancy-stepper-step` | each `<li>` | - |
+| `data-state` | each `<li>` | `upcoming` / `current` / `complete` / `error` |
+| `data-index` | each `<li>` | the step's index |
+| `data-step-id` | each `<li>` | the step's `id`, when given |
+| `data-disabled` | each `<li>` | `true` when disabled |
+| `data-react-fancy-stepper-trigger` | the step's `<button>` | only when `clickable` |
+| `data-react-fancy-stepper-indicator` / `-title` / `-description` / `-content` / `-state` | the step's parts | - |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/react-fancy",
-  "version": "6.2.0",
+  "version": "6.4.0",
   "description": "React UI component library for Human+ UX — controlled, agent-bridgeable primitives",
   "repository": {
     "type": "git",
@@ -203,6 +203,16 @@
         "default": "./dist/checkbox-group.cjs"
       }
     },
+    "./code-block": {
+      "import": {
+        "types": "./dist/code-block.d.ts",
+        "default": "./dist/code-block.js"
+      },
+      "require": {
+        "types": "./dist/code-block.d.cts",
+        "default": "./dist/code-block.cjs"
+      }
+    },
     "./code-view": {
       "import": {
         "types": "./dist/code-view.d.ts",
@@ -873,6 +883,16 @@
         "default": "./dist/stat-list.cjs"
       }
     },
+    "./stepper": {
+      "import": {
+        "types": "./dist/stepper.d.ts",
+        "default": "./dist/stepper.js"
+      },
+      "require": {
+        "types": "./dist/stepper.d.cts",
+        "default": "./dist/stepper.cjs"
+      }
+    },
     "./sticky-note": {
       "import": {
         "types": "./dist/sticky-note.d.ts",