@openpawlabs/diy-guides-ui 1.0.0

package/README.md

@@ -0,0 +1,126 @@
+# @openpawlabs/diy-guides-ui
+
+Open-source React UI library for building **iFixit-style DIY guides** — step-by-step instructions with tools, warnings, and media.
+
+## Status
+
+Active development. The core guide component set is implemented, tested, and documented in Storybook:
+
+| Component | Purpose |
+|-----------|---------|
+| `GuideLayout` | Responsive page shell: header, intro + tools row, full-width steps |
+| `GuideStepList` | Auto-numbered step sequence with a derived progress bar |
+| `GuideStep` | A single step — number badge, completion checkbox, media, and bulleted instructions |
+| `MediaFigure` | Image/video with percentage-positioned annotation markers |
+| `ToolList` | Titled card of required tools and parts |
+| `Callout` | Safety / informational callout (`note` → `danger` types) |
+| `DifficultyBadge` | Color-coded difficulty pill (easy / moderate / difficult) |
+
+Guide colors (`COLORS` / `GuideColor`) link step bullet dots to image annotation markers. Callout types (`CalloutType`) drive safety and informational tone in `Callout` boxes.
+
+## Tech stack
+
+- [React](https://react.dev/) 19 + TypeScript
+- [HeroUI v3](https://heroui.com/) for accessible UI primitives
+- [Tailwind CSS v4](https://tailwindcss.com/)
+- [Storybook](https://storybook.js.org/) for component development
+- [Vite](https://vite.dev/) library mode for publishing
+- [Vitest](https://vitest.dev/) + React Testing Library
+
+## Getting started (development)
+
+Requires [pnpm](https://pnpm.io/) 9+.
+
+```bash
+pnpm install
+pnpm dev        # Storybook at http://localhost:6006
+pnpm test       # Run tests
+pnpm build      # Build library to dist/
+```
+
+## Project structure
+
+```
+src/
+  components/     # One folder per component (tsx, stories, tests, index)
+  hooks/          # Shared hooks (e.g. useControlledState)
+  types/          # Shared design tokens (colors, callout types) and types
+  styles/         # Tailwind + HeroUI CSS entry
+  index.ts        # Public API exports
+.storybook/       # Storybook configuration
+```
+
+See [AGENTS.md](./AGENTS.md) for contributor and AI agent conventions.
+
+## Using in another app
+
+```bash
+pnpm add @openpawlabs/diy-guides-ui @heroui/react @heroui/styles tailwindcss
+```
+
+Import styles in your app CSS:
+
+```css
+@import "tailwindcss";
+@import "@heroui/styles";
+@import "@openpawlabs/diy-guides-ui/styles";
+```
+
+```tsx
+import "@openpawlabs/diy-guides-ui/styles";
+import {
+  GuideLayout,
+  GuideStepList,
+  GuideStep,
+  MediaFigure,
+  ToolList,
+  Callout,
+} from "@openpawlabs/diy-guides-ui";
+
+export function BatteryGuide() {
+  return (
+    <GuideLayout>
+      <GuideLayout.Header
+        title="Replace a Smartphone Battery"
+        difficulty="moderate"
+        timeEstimate="20 – 30 minutes"
+      />
+
+      <GuideLayout.Intro>
+        A worn battery drains fast and can swell. This guide covers a safe swap.
+      </GuideLayout.Intro>
+
+      <GuideLayout.Sidebar>
+        <ToolList title="Tools">
+          <ToolList.Item name="Pro Tech Toolkit" href="#" price="$67.96" />
+        </ToolList>
+      </GuideLayout.Sidebar>
+
+      <GuideLayout.Content>
+        <Callout type="danger" title="Battery safety">
+          A punctured lithium battery can catch fire. Work slowly.
+        </Callout>
+        <GuideStepList>
+          <GuideStep title="Open the case">
+            <GuideStep.Media>
+              <MediaFigure
+                src="/step-1.jpg"
+                annotations={[{ x: 50, y: 45, color: "ORANGE", label: 1 }]}
+              />
+            </GuideStep.Media>
+            <GuideStep.Bullets>
+              <GuideStep.Bullet color="ORANGE">
+                Soften the adhesive with even heat before prying.
+              </GuideStep.Bullet>
+            </GuideStep.Bullets>
+          </GuideStep>
+        </GuideStepList>
+      </GuideLayout.Content>
+    </GuideLayout>
+  );
+}
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/components/Callout/Callout.d.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+import { type CalloutType } from "../../types/callout";
+export interface CalloutProps {
+    /** Tone of the callout — controls color, default icon, and default title. @default "caution" */
+    type?: CalloutType;
+    /** Heading text. Pass `null` to omit. Defaults to the callout type label. */
+    title?: ReactNode;
+    /** Override the leading indicator icon. */
+    icon?: ReactNode;
+    /** Callout body. */
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * Safety / informational callout for guides — battery, heat, ESD, and other
+ * hazards. Wraps HeroUI `Alert`, mapping {@link CalloutType} to a guide
+ * palette accent, default icon, and title so a single `type` prop styles the
+ * whole box.
+ */
+export declare function Callout({ type, title, icon, children, className, }: CalloutProps): import("react").JSX.Element;
+//# sourceMappingURL=Callout.d.ts.map

package/dist/components/Callout/Callout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Callout.d.ts","sourceRoot":"","sources":["../../../src/components/Callout/Callout.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,EACL,KAAK,WAAW,EAGjB,MAAM,qBAAqB,CAAC;AAG7B,MAAM,WAAW,YAAY;IAC3B,gGAAgG;IAChG,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,oBAAoB;IACpB,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA6CD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,EACtB,IAAgB,EAChB,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,SAAS,GACV,EAAE,YAAY,+BAqBd"}

package/dist/components/Callout/Callout.stories.d.ts

@@ -0,0 +1,31 @@
+import type { StoryObj } from "@storybook/react-vite";
+import { Callout } from "./Callout";
+declare const meta: {
+    title: string;
+    component: typeof Callout;
+    tags: string[];
+    parameters: {
+        docs: {
+            description: {
+                component: string;
+            };
+        };
+    };
+    argTypes: {
+        type: {
+            control: "inline-radio";
+            options: string[];
+        };
+    };
+    args: {
+        type: "caution";
+        children: string;
+    };
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const Default: Story;
+export declare const AllTypes: Story;
+export declare const CustomTitle: Story;
+export declare const TitleHidden: Story;
+//# sourceMappingURL=Callout.stories.d.ts.map

package/dist/components/Callout/Callout.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Callout.stories.d.ts","sourceRoot":"","sources":["../../../src/components/Callout/Callout.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyBpC,QAAA,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;CAkBsB,CAAC;AAEjC,eAAe,IAAI,CAAC;AAEpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAEnC,eAAO,MAAM,OAAO,EAAE,KASrB,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,KA4BtB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,KAezB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,KAczB,CAAC"}

package/dist/components/Callout/Callout.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Callout.test.d.ts.map

package/dist/components/Callout/Callout.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Callout.test.d.ts","sourceRoot":"","sources":["../../../src/components/Callout/Callout.test.tsx"],"names":[],"mappings":""}

package/dist/components/Callout/index.d.ts

@@ -0,0 +1,3 @@
+export { Callout } from "./Callout";
+export type { CalloutProps } from "./Callout";
+//# sourceMappingURL=index.d.ts.map

package/dist/components/Callout/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/Callout/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC"}

package/dist/components/DifficultyBadge/DifficultyBadge.d.ts

@@ -0,0 +1,20 @@
+import type { ReactNode } from "react";
+/** Relative effort required to complete a guide. */
+export type Difficulty = "easy" | "moderate" | "difficult";
+export interface DifficultyBadgeProps {
+    /** Difficulty level — controls color and default label. */
+    difficulty: Difficulty;
+    /** Override the displayed text (defaults to a capitalized level name). */
+    label?: ReactNode;
+    /** Show the leading gauge icon. @default true */
+    showIcon?: boolean;
+    /** Chip size. @default "md" */
+    size?: "sm" | "md" | "lg";
+    className?: string;
+}
+/**
+ * Compact, color-coded indicator of how hard a guide is, built on HeroUI `Chip`.
+ * Mirrors iFixit's difficulty pill (easy → green, moderate → orange, difficult → red).
+ */
+export declare function DifficultyBadge({ difficulty, label, showIcon, size, className, }: DifficultyBadgeProps): import("react").JSX.Element;
+//# sourceMappingURL=DifficultyBadge.d.ts.map

package/dist/components/DifficultyBadge/DifficultyBadge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DifficultyBadge.d.ts","sourceRoot":"","sources":["../../../src/components/DifficultyBadge/DifficultyBadge.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC,oDAAoD;AACpD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,UAAU,GAAG,WAAW,CAAC;AAc3D,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,UAAU,EAAE,UAAU,CAAC;IACvB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+BAA+B;IAC/B,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAqBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAC9B,UAAU,EACV,KAAK,EACL,QAAe,EACf,IAAW,EACX,SAAS,GACV,EAAE,oBAAoB,+BAiBtB"}

package/dist/components/DifficultyBadge/DifficultyBadge.stories.d.ts

@@ -0,0 +1,37 @@
+import type { StoryObj } from "@storybook/react-vite";
+import { DifficultyBadge } from "./DifficultyBadge";
+declare const meta: {
+    title: string;
+    component: typeof DifficultyBadge;
+    tags: string[];
+    parameters: {
+        docs: {
+            description: {
+                component: string;
+            };
+        };
+    };
+    argTypes: {
+        difficulty: {
+            control: "inline-radio";
+            options: string[];
+        };
+        size: {
+            control: "inline-radio";
+            options: string[];
+        };
+    };
+    args: {
+        difficulty: "moderate";
+        showIcon: true;
+        size: "md";
+    };
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const Default: Story;
+export declare const AllLevels: Story;
+export declare const Sizes: Story;
+export declare const WithoutIcon: Story;
+export declare const CustomLabel: Story;
+//# sourceMappingURL=DifficultyBadge.stories.d.ts.map

package/dist/components/DifficultyBadge/DifficultyBadge.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DifficultyBadge.stories.d.ts","sourceRoot":"","sources":["../../../src/components/DifficultyBadge/DifficultyBadge.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAqBpD,QAAA,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;CAmB8B,CAAC;AAEzC,eAAe,IAAI,CAAC;AAEpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAEnC,eAAO,MAAM,OAAO,EAAE,KASrB,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,KAgBvB,CAAC;AAEF,eAAO,MAAM,KAAK,EAAE,KAgBnB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,KASzB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,KAUzB,CAAC"}

package/dist/components/DifficultyBadge/DifficultyBadge.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=DifficultyBadge.test.d.ts.map

package/dist/components/DifficultyBadge/DifficultyBadge.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DifficultyBadge.test.d.ts","sourceRoot":"","sources":["../../../src/components/DifficultyBadge/DifficultyBadge.test.tsx"],"names":[],"mappings":""}

package/dist/components/DifficultyBadge/index.d.ts

@@ -0,0 +1,3 @@
+export { DifficultyBadge } from "./DifficultyBadge";
+export type { DifficultyBadgeProps, Difficulty } from "./DifficultyBadge";
+//# sourceMappingURL=index.d.ts.map

package/dist/components/DifficultyBadge/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/DifficultyBadge/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/components/GuideLayout/GuideLayout.d.ts

@@ -0,0 +1,49 @@
+import type { ReactNode } from "react";
+import { type Difficulty } from "../DifficultyBadge";
+export interface GuideLayoutProps {
+    /** `GuideLayout.Header`, `GuideLayout.Intro`, `GuideLayout.Sidebar`, and `GuideLayout.Content`. */
+    children: ReactNode;
+    className?: string;
+}
+export interface GuideLayoutHeaderProps {
+    /** Guide title. */
+    title: ReactNode;
+    /** Difficulty level — rendered as a `DifficultyBadge`. */
+    difficulty?: Difficulty;
+    /** Time estimate text, e.g. "20 – 30 minutes". */
+    timeEstimate?: ReactNode;
+    /** Byline / metadata line (contributors, last updated, …). */
+    meta?: ReactNode;
+    className?: string;
+}
+export interface GuideLayoutIntroProps {
+    /** Introduction / overview copy beside the tools sidebar. */
+    children: ReactNode;
+    className?: string;
+}
+declare function GuideLayoutHeader({ title, difficulty, timeEstimate, meta, className, }: GuideLayoutHeaderProps): import("react").JSX.Element;
+/** Introduction column — sits left of `Sidebar` on desktop. */
+declare function GuideLayoutIntro({ children, className }: GuideLayoutIntroProps): import("react").JSX.Element;
+/** "What you need" column — sits right of `Intro` on desktop. */
+declare function GuideLayoutSidebar({ children, className, }: {
+    children: ReactNode;
+    className?: string;
+}): import("react").JSX.Element;
+/** Full-width main column — typically holds a `GuideStepList`. */
+declare function GuideLayoutContent({ children, className, }: {
+    children: ReactNode;
+    className?: string;
+}): import("react").JSX.Element;
+/**
+ * Responsive page shell for a guide: a full-width `Header`, an intro row with
+ * `Intro` (description) beside `Sidebar` (tools/parts), then full-width `Content`
+ * (steps). On mobile the intro row stacks with intro first, then sidebar.
+ */
+export declare const GuideLayout: (({ children, className }: GuideLayoutProps) => import("react").JSX.Element) & {
+    Header: typeof GuideLayoutHeader;
+    Intro: typeof GuideLayoutIntro;
+    Sidebar: typeof GuideLayoutSidebar;
+    Content: typeof GuideLayoutContent;
+};
+export {};
+//# sourceMappingURL=GuideLayout.d.ts.map

package/dist/components/GuideLayout/GuideLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuideLayout.d.ts","sourceRoot":"","sources":["../../../src/components/GuideLayout/GuideLayout.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,EAEL,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,gBAAgB;IAC/B,mGAAmG;IACnG,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,mBAAmB;IACnB,KAAK,EAAE,SAAS,CAAC;IACjB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,kDAAkD;IAClD,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,iBAAS,iBAAiB,CAAC,EACzB,KAAK,EACL,UAAU,EACV,YAAY,EACZ,IAAI,EACJ,SAAS,GACV,EAAE,sBAAsB,+BA6BxB;AAED,+DAA+D;AAC/D,iBAAS,gBAAgB,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,qBAAqB,+BAMvE;AAED,iEAAiE;AACjE,iBAAS,kBAAkB,CAAC,EAC1B,QAAQ,EACR,SAAS,GACV,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,+BAMA;AAED,kEAAkE;AAClE,iBAAS,kBAAkB,CAAC,EAC1B,QAAQ,EACR,SAAS,GACV,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,+BAMA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,6BAC4B,gBAAgB;;;;;CAkBnE,CAAC"}

package/dist/components/GuideLayout/GuideLayout.stories.d.ts

@@ -0,0 +1,33 @@
+import type { StoryObj } from "@storybook/react-vite";
+declare const meta: {
+    title: string;
+    component: (({ children, className }: import("./GuideLayout").GuideLayoutProps) => import("react").JSX.Element) & {
+        Header: ({ title, difficulty, timeEstimate, meta, className, }: import("./GuideLayout").GuideLayoutHeaderProps) => import("react").JSX.Element;
+        Intro: ({ children, className }: import("./GuideLayout").GuideLayoutIntroProps) => import("react").JSX.Element;
+        Sidebar: ({ children, className, }: {
+            children: import("react").ReactNode;
+            className?: string;
+        }) => import("react").JSX.Element;
+        Content: ({ children, className, }: {
+            children: import("react").ReactNode;
+            className?: string;
+        }) => import("react").JSX.Element;
+    };
+    parameters: {
+        layout: string;
+        docs: {
+            description: {
+                component: string;
+            };
+        };
+    };
+    tags: string[];
+    args: {
+        children: null;
+    };
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const FullGuide: Story;
+export declare const WithoutSidebar: Story;
+//# sourceMappingURL=GuideLayout.stories.d.ts.map

package/dist/components/GuideLayout/GuideLayout.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuideLayout.stories.d.ts","sourceRoot":"","sources":["../../../src/components/GuideLayout/GuideLayout.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AA4B5D,QAAA,MAAM,IAAI;;;;;;;qBAyCwB,CAAC;;;;qBAOvB,CAAC;;;;;;;;;;;;;;;CAvCuB,CAAC;AAErC,eAAe,IAAI,CAAC;AAEpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAEnC,eAAO,MAAM,SAAS,EAAE,KAsGvB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,KAsD5B,CAAC"}

package/dist/components/GuideLayout/GuideLayout.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=GuideLayout.test.d.ts.map

package/dist/components/GuideLayout/GuideLayout.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuideLayout.test.d.ts","sourceRoot":"","sources":["../../../src/components/GuideLayout/GuideLayout.test.tsx"],"names":[],"mappings":""}

package/dist/components/GuideLayout/index.d.ts

@@ -0,0 +1,3 @@
+export { GuideLayout } from "./GuideLayout";
+export type { GuideLayoutProps, GuideLayoutHeaderProps, GuideLayoutIntroProps, } from "./GuideLayout";
+//# sourceMappingURL=index.d.ts.map

package/dist/components/GuideLayout/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/GuideLayout/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,eAAe,CAAC"}

package/dist/components/GuideStep/GuideStep.d.ts

@@ -0,0 +1,62 @@
+import { type ReactNode } from "react";
+import { type GuideColor } from "../../types/colors";
+export interface GuideStepProps {
+    /** Step number shown in the badge. Auto-assigned when inside `GuideStepList`. */
+    number?: number;
+    /** Step heading. */
+    title?: ReactNode;
+    /** Controlled completion state. */
+    isCompleted?: boolean;
+    /** Initial completion state when uncontrolled. @default false */
+    defaultCompleted?: boolean;
+    /** Fires whenever completion changes (controlled or not). */
+    onCompletedChange?: (completed: boolean) => void;
+    /** Render the "mark complete" checkbox. @default true */
+    completable?: boolean;
+    /** Step body — requires `GuideStep.Media` (≥1 image) and `GuideStep.Bullets` (≥1 bullet). */
+    children?: ReactNode;
+    className?: string;
+}
+/** Bullet presentation — `dot` uses a colored dot; others use semantic icons and labels. */
+export type GuideStepBulletVariant = "dot" | "caution" | "reminder" | "note";
+export interface GuideStepBulletProps {
+    /**
+     * Bullet style. `dot` renders a colored dot (link to `MediaFigure`
+     * annotations); `caution`, `reminder`, and `note` render iFixit-style semantic bullets.
+     * @default "dot"
+     */
+    variant?: GuideStepBulletVariant;
+    /** Marker color for `dot` bullets — match a related `MediaFigure` annotation. @default "GREY" */
+    color?: GuideColor;
+    /** Override the auto-generated label for semantic bullet types. */
+    label?: ReactNode;
+    /** Hide the auto-generated label for `caution`, `reminder`, and `note` bullets. */
+    hideLabel?: boolean;
+    children: ReactNode;
+    className?: string;
+}
+/** Slot for up to three `MediaFigure`s — parent renders main image + hover thumbnails. */
+declare function GuideStepMedia(_props: {
+    children?: ReactNode;
+}): null;
+/** Ordered container for `GuideStep.Bullet`s. */
+declare function GuideStepBullets({ children, className, }: {
+    children: ReactNode;
+    className?: string;
+}): import("react").JSX.Element;
+/** A single instruction line — dot bullets or semantic caution / reminder / note bullets. */
+declare function GuideStepBullet({ variant, color, label, hideLabel, children, className, }: GuideStepBulletProps): import("react").JSX.Element;
+declare function GuideStepRoot({ number, title, isCompleted, defaultCompleted, onCompletedChange, completable, children, className, }: GuideStepProps): import("react").JSX.Element;
+/**
+ * A single numbered guide step: header with number badge and optional completion
+ * checkbox, plus a two-column body (main image left, thumbnails + bullets right).
+ * Requires at least one `MediaFigure` in `GuideStep.Media` and one `GuideStep.Bullet`
+ * in `GuideStep.Bullets`. Up to three images share a hover thumbnail gallery.
+ */
+export declare const GuideStep: typeof GuideStepRoot & {
+    Media: typeof GuideStepMedia;
+    Bullets: typeof GuideStepBullets;
+    Bullet: typeof GuideStepBullet;
+};
+export {};
+//# sourceMappingURL=GuideStep.d.ts.map

package/dist/components/GuideStep/GuideStep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuideStep.d.ts","sourceRoot":"","sources":["../../../src/components/GuideStep/GuideStep.tsx"],"names":[],"mappings":"AAEA,OAAO,EAQL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAIf,OAAO,EAAU,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAW7D,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,mCAAmC;IACnC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,6DAA6D;IAC7D,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;IACjD,yDAAyD;IACzD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,4FAA4F;AAC5F,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;AAE7E,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC,iGAAiG;IACjG,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,mEAAmE;IACnE,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,mFAAmF;IACnF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA0HD,0FAA0F;AAC1F,iBAAS,cAAc,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,QAEvD;AAED,iDAAiD;AACjD,iBAAS,gBAAgB,CAAC,EACxB,QAAQ,EACR,SAAS,GACV,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,+BAIA;AAED,6FAA6F;AAC7F,iBAAS,eAAe,CAAC,EACvB,OAAe,EACf,KAAc,EACd,KAAK,EACL,SAAiB,EACjB,QAAQ,EACR,SAAS,GACV,EAAE,oBAAoB,+BA2CtB;AA2ED,iBAAS,aAAa,CAAC,EACrB,MAAM,EACN,KAAK,EACL,WAAW,EACX,gBAAwB,EACxB,iBAAiB,EACjB,WAAkB,EAClB,QAAQ,EACR,SAAS,GACV,EAAE,cAAc,+BAkFhB;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;;CAIpB,CAAC"}

package/dist/components/GuideStep/GuideStep.stories.d.ts

@@ -0,0 +1,36 @@
+import type { StoryObj } from "@storybook/react-vite";
+declare const meta: {
+    title: string;
+    component: (({ number, title, isCompleted, defaultCompleted, onCompletedChange, completable, children, className, }: import("./GuideStep").GuideStepProps) => import("react").JSX.Element) & {
+        Media: (_props: {
+            children?: import("react").ReactNode;
+        }) => null;
+        Bullets: ({ children, className, }: {
+            children: import("react").ReactNode;
+            className?: string;
+        }) => import("react").JSX.Element;
+        Bullet: ({ variant, color, label, hideLabel, children, className, }: import("./GuideStep").GuideStepBulletProps) => import("react").JSX.Element;
+    };
+    tags: string[];
+    parameters: {
+        docs: {
+            description: {
+                component: string;
+            };
+        };
+    };
+    args: {
+        number: number;
+        title: string;
+        completable: true;
+    };
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const Anatomy: Story;
+export declare const MultipleImages: Story;
+export declare const DotBullets: Story;
+export declare const SemanticBullets: Story;
+export declare const Completed: Story;
+export declare const WithoutCompletion: Story;
+//# sourceMappingURL=GuideStep.stories.d.ts.map

package/dist/components/GuideStep/GuideStep.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuideStep.stories.d.ts","sourceRoot":"","sources":["../../../src/components/GuideStep/GuideStep.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAqD5D,QAAA,MAAM,IAAI;;;;oBAuHA,CAAA;;;;qBAKA,CAAC;;;;;;;;;;;;;;;;;CAhHuB,CAAC;AAEnC,eAAe,IAAI,CAAC;AAEpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAEnC,eAAO,MAAM,OAAO,EAAE,KAgCrB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,KAmC5B,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,KAsCxB,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,KAoC7B,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,KAwBvB,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,KA0B/B,CAAC"}

package/dist/components/GuideStep/GuideStep.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=GuideStep.test.d.ts.map

package/dist/components/GuideStep/GuideStep.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuideStep.test.d.ts","sourceRoot":"","sources":["../../../src/components/GuideStep/GuideStep.test.tsx"],"names":[],"mappings":""}

package/dist/components/GuideStep/index.d.ts

@@ -0,0 +1,3 @@
+export { GuideStep } from "./GuideStep";
+export type { GuideStepProps, GuideStepBulletProps, GuideStepBulletVariant } from "./GuideStep";
+//# sourceMappingURL=index.d.ts.map

package/dist/components/GuideStep/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/GuideStep/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC"}

package/dist/components/GuideStepList/GuideStepList.d.ts

@@ -0,0 +1,21 @@
+import { type ReactNode } from "react";
+export interface GuideProgress {
+    completed: number;
+    total: number;
+}
+export interface GuideStepListProps {
+    /** `GuideStep` children — numbered automatically in order. */
+    children: ReactNode;
+    /** Show the aggregate progress bar. @default true */
+    showProgress?: boolean;
+    /** Fires whenever the number of completed steps changes. */
+    onProgressChange?: (progress: GuideProgress) => void;
+    className?: string;
+}
+/**
+ * Ordered sequence of `GuideStep`s. Numbers each step in order, owns their
+ * completion state, and renders a derived progress bar — so a guide author only
+ * has to drop in steps. Listen to overall progress via `onProgressChange`.
+ */
+export declare function GuideStepList({ children, showProgress, onProgressChange, className, }: GuideStepListProps): import("react").JSX.Element;
+//# sourceMappingURL=GuideStepList.d.ts.map

package/dist/components/GuideStepList/GuideStepList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuideStepList.d.ts","sourceRoot":"","sources":["../../../src/components/GuideStepList/GuideStepList.tsx"],"names":[],"mappings":"AAEA,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAIf,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,QAAQ,EAAE,SAAS,CAAC;IACpB,qDAAqD;IACrD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAC;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAC5B,QAAQ,EACR,YAAmB,EACnB,gBAAgB,EAChB,SAAS,GACV,EAAE,kBAAkB,+BAmEpB"}

package/dist/components/GuideStepList/GuideStepList.stories.d.ts

@@ -0,0 +1,23 @@
+import type { StoryObj } from "@storybook/react-vite";
+import { GuideStepList } from "./GuideStepList";
+declare const meta: {
+    title: string;
+    component: typeof GuideStepList;
+    tags: string[];
+    parameters: {
+        docs: {
+            description: {
+                component: string;
+            };
+        };
+    };
+    args: {
+        children: null;
+    };
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const Default: Story;
+export declare const WithStartingProgress: Story;
+export declare const WithoutProgressBar: Story;
+//# sourceMappingURL=GuideStepList.stories.d.ts.map

package/dist/components/GuideStepList/GuideStepList.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuideStepList.stories.d.ts","sourceRoot":"","sources":["../../../src/components/GuideStepList/GuideStepList.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAkBhD,QAAA,MAAM,IAAI;;;;;;;;;;;;;;CAQ4B,CAAC;AAEvC,eAAe,IAAI,CAAC;AAEpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAEnC,eAAO,MAAM,OAAO,EAAE,KAqDrB,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,KAmClC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,KAmChC,CAAC"}

package/dist/components/GuideStepList/GuideStepList.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=GuideStepList.test.d.ts.map

package/dist/components/GuideStepList/GuideStepList.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuideStepList.test.d.ts","sourceRoot":"","sources":["../../../src/components/GuideStepList/GuideStepList.test.tsx"],"names":[],"mappings":""}

package/dist/components/GuideStepList/index.d.ts

@@ -0,0 +1,3 @@
+export { GuideStepList } from "./GuideStepList";
+export type { GuideStepListProps, GuideProgress } from "./GuideStepList";
+//# sourceMappingURL=index.d.ts.map

package/dist/components/GuideStepList/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/GuideStepList/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}