storybook-addon-designbook 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Storybook contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,262 @@
+<!-- README START -->
+
+# Storybook Addon Kit ([demo](https://main--601ada52c3d4040021afdc30.chromatic.com))
+
+Simplify the creation of Storybook addons
+
+- 📝 Live-editing in development
+- ⚛️ React/JSX support
+- 📦 Transpiling and bundling with [tsup](https://tsup.egoist.dev/)
+- 🏷 Plugin metadata
+- 🚢 Release management with [Auto](https://github.com/intuit/auto)
+- 🧺 Boilerplate and sample code
+- 🛄 ESM support
+- 🛂 TypeScript by default with option to eject to JS
+
+### Migrating to a later Storybook version
+
+If you have an existing addon that you want to migrate to support the latest version of Storyboook, you can check out the [addon migration guide](https://storybook.js.org/docs/addons/addon-migration-guide).
+
+## Getting Started
+
+Click the **Use this template** button to get started.
+
+![](https://user-images.githubusercontent.com/321738/125058439-8d9ef880-e0aa-11eb-9211-e6d7be812959.gif)
+
+Clone your repository and install dependencies.
+
+```sh
+npm install
+```
+
+<!-- README END -->
+
+### Development scripts
+
+- `npm run start` runs babel in watch mode and starts Storybook
+- `npm run build` build and package your addon code
+
+### Switch from TypeScript to JavaScript
+
+Don't want to use TypeScript? We offer a handy eject command: `npm run eject-ts`
+
+This will convert all code to JS. It is a destructive process, so we recommended running this before you start writing any code.
+
+## What's included?
+
+![Demo](https://user-images.githubusercontent.com/42671/107857205-e7044380-6dfa-11eb-8718-ad02e3ba1a3f.gif)
+
+The addon code lives in `src`. It demonstrates all core addon related concepts. The three [UI paradigms](https://storybook.js.org/docs/react/addons/addon-types#ui-based-addons)
+
+- `src/Tool.tsx`
+- `src/Panel.tsx`
+- `src/Tab.tsx`
+
+Which, along with the addon itself, are registered in `src/manager.ts`.
+
+Managing State and interacting with a story:
+
+- `src/withGlobals.ts` & `src/Tool.tsx` demonstrates how to use `useGlobals` to manage global state and modify the contents of a Story.
+- `src/withRoundTrip.ts` & `src/Panel.tsx` demonstrates two-way communication using channels.
+- `src/Tab.tsx` demonstrates how to use `useParameter` to access the current story's parameters.
+
+Your addon might use one or more of these patterns. Feel free to delete unused code. Update `src/manager.ts` and `src/preview.ts` accordingly.
+
+Lastly, configure you addon name in `src/constants.ts`.
+
+### Bundling
+
+Addons can interact with a Storybook project in multiple ways. It is recommended to familiarize yourself with [the basics](https://storybook.js.org/docs/react/addons/introduction) before getting started.
+
+- Manager entries are used to add UI or behavior to the Storybook manager UI.
+- Preview entries are used to add UI or behavior to the preview iframe where stories are rendered.
+- Presets are used to modify the Storybook configuration, similar to how [users can configure their `main.ts` configurations](https://storybook.js.org/docs/react/api/main-config).
+
+Since each of these places represents a different environment with different features and modules, it is also recommended to split and build your modules accordingly. This addon-kit comes with a preconfigured [bundling configuration](./tsup.config.ts) that supports this split, and you are free to modify and extend it as needed.
+
+You can define which modules match which environments in the [`package.json#bundler`](./package.json) property:
+
+- `exportEntries` is a list of module entries that users can manually import from anywhere they need to. For example, you could have decorators that users need to import into their `preview.ts` file or utility functions that can be used in their `main.ts` files.
+- `managerEntries` is a list of module entries meant only for the manager UI. These modules will be bundled to ESM and won't include types since they are mostly loaded by Storybook directly.
+- `previewEntries` is a list of module entries meant only for the preview UI. These modules will be bundled to ESM and won't include types since they are mostly loaded by Storybook directly.
+
+Manager and preview entries are only used in the browser so they only output ESM modules. Export entries could be used both in the browser and in Node depending on their use case, so they both output ESM and CJS modules.
+
+#### Globalized packages
+
+Storybook provides a predefined set of packages that are available in the manager UI and the preview UI. In the final bundle of your addon, these packages should not be included. Instead, the imports should stay in place, allowing Storybook to replace those imports with the actual packages during the Storybook build process.
+
+The list of packages differs between the manager and the preview, which is why there is a slight difference between `managerEntries` and `previewEntries`. Most notably, `react` and `react-dom` are prebundled in the manager but not in the preview. This means that your manager entries can use React to build UI without bundling it or having a direct reference to it. Therefore, it is safe to have React as a `devDependency` even though you are using it in production. _Requiring React as a peer dependency would unnecessarily force your users to install React._
+
+An exception to this rule is if you are using React to inject UI into the preview, which does not come prebundled with React. In such cases, you need to move `react` and `react-dom` to a peer dependency. However, we generally advise against this pattern since it would limit the usage of your addon to React-based Storybooks.
+
+### Metadata
+
+Storybook addons are listed in the [catalog](https://storybook.js.org/addons) and distributed via npm. The catalog is populated by querying npm's registry for Storybook-specific metadata in `package.json`. This project has been configured with sample data. Learn more about available options in the [Addon metadata docs](https://storybook.js.org/docs/react/addons/addon-catalog#addon-metadata).
+
+## Documentation
+
+To help the community use your addon and understand its capabilities, please document it thoroughly.
+
+To get started, replace this README with the content in this sample template.
+
+### Sample documentation template
+
+````md
+# My Addon
+
+## Installation
+
+First, install the package.
+
+```sh
+npm install --save-dev my-addon
+```
+
+Then, register it as an addon in `.storybook/main.js`.
+
+```ts
+// .storybook/main.ts
+
+// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
+import type { StorybookConfig } from '@storybook/your-framework';
+
+const config: StorybookConfig = {
+  // ...rest of config
+  addons: [
+    '@storybook/addon-docs'
+    'my-addon', // 👈 register the addon here
+  ],
+};
+
+export default config;
+```
+
+## Usage
+
+The primary way to use this addon is to define the `exampleParameter` parameter. You can do this the
+component level, as below, to affect all stories in the file, or you can do it for a single story.
+
+```ts
+// Button.stories.ts
+
+// Replace your-framework with the name of your framework
+import type { Meta } from '@storybook/your-framework';
+
+import { Button } from './Button';
+
+const meta: Meta<typeof Button> = {
+  component: Button,
+  parameters: {
+    myAddon: {
+      exampleParameter: true,
+      // See API section below for available parameters
+    },
+  },
+};
+
+export default meta;
+```
+
+Another way to use the addon is...
+
+## API
+
+### Parameters
+
+This addon contributes the following parameters to Storybook, under the `myAddon` namespace:
+
+#### `disable`
+
+Type: `boolean`
+
+Disable this addon's behavior. This parameter is most useful to allow overriding at more specific
+levels. For example, if this parameter is set to true at the project level, it could then be
+re-enabled by setting it to false at the meta (component) or story level.
+
+### Options
+
+When registering this addon, you can configure it with the following options, which are passed when
+registering the addon, like so:
+
+```ts
+// .storybook/main.ts
+
+// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
+import type { StorybookConfig } from '@storybook/your-framework';
+
+const config: StorybookConfig = {
+  // ...rest of config
+  addons: [
+    '@storybook/addon-docs',
+    {
+      name: 'my-addon',
+      options: {
+        // 👈 options for my-addon go here
+      },
+    },
+  ],
+};
+
+export default config;
+```
+
+#### `useExperimentalBehavior`
+
+Type: `boolean`
+
+Enable experimental behavior to...
+````
+
+## Release Management
+
+### Setup
+
+This project is configured to use [auto](https://github.com/intuit/auto) for release management. It generates a changelog and pushes it to both GitHub and npm. Therefore, you need to configure access to both:
+
+- [`NPM_TOKEN`](https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-access-tokens) Create a token with both _Read and Publish_ permissions.
+- [`GH_TOKEN`](https://github.com/settings/tokens) Create a token with the `repo` scope.
+
+Then open your `package.json` and edit the following fields:
+
+- `name`
+- `author`
+- `repository`
+
+#### Local
+
+To use `auto` locally create a `.env` file at the root of your project and add your tokens to it:
+
+```bash
+GH_TOKEN=<value you just got from GitHub>
+NPM_TOKEN=<value you just got from npm>
+```
+
+Lastly, **create labels on GitHub**. You’ll use these labels in the future when making changes to the package.
+
+```bash
+npx auto create-labels
+```
+
+If you check on GitHub, you’ll now see a set of labels that `auto` would like you to use. Use these to tag future pull requests.
+
+#### GitHub Actions
+
+This template comes with GitHub actions already set up to publish your addon anytime someone pushes to your repository.
+
+Go to `Settings > Secrets`, click `New repository secret`, and add your `NPM_TOKEN`.
+
+### Creating a release
+
+To create a release locally you can run the following command, otherwise the GitHub action will make the release for you.
+
+```sh
+npm run release
+```
+
+That will:
+
+- Build and package the addon code
+- Bump the version
+- Push a release to GitHub and npm
+- Push a changelog to GitHub

package/dist/components/DeboSection.jsx

@@ -0,0 +1,79 @@
+import { useDesignbookData } from '../hooks/useDesignbookData.js';
+import { DeboEmptyState } from './ui/DeboEmptyState.jsx';
+import { DeboLoading } from './ui/DeboLoading.jsx';
+import { DeboPageLayout } from './ui/DeboPageLayout.jsx';
+import { DeboSourceFooter } from './ui/DeboSourceFooter.jsx';
+import { DeboAlert } from './ui/DeboAlert.jsx';
+
+/**
+ * DeboSection — Page section that combines data loading, empty state,
+ * content rendering, reload button, and AI command reference.
+ *
+ * @param {Object} props
+ * @param {string} props.dataPath — Relative path within designbook/ to load
+ * @param {(markdown: string) => any} props.parser — Markdown-to-data parser
+ * @param {string} props.command — AI command name (e.g., "/product-roadmap")
+ * @param {string} props.emptyMessage — Displayed when no data exists
+ * @param {(data: any) => React.ReactNode} props.renderContent — How to render the loaded data
+ * @param {string} [props.title] — Section heading displayed above the content
+ * @param {string} [props.filePath] — Full file path for display in empty state
+ * @param {boolean} [props.bare=false] — If true, renders content/loading/error/empty
+ *   without DeboPageLayout, DeboSourceFooter, or command hint. Use when composing
+ *   inside an outer layout (e.g., DeboStepIndicator or DeboPageLayout).
+ */
+export function DeboSection({ dataPath, parser, command, emptyMessage, renderContent, title, filePath, bare = false }) {
+  const { data, loading, error, reload } = useDesignbookData(dataPath, parser);
+
+  const displayPath = filePath || `designbook/${dataPath}`;
+
+  const heading = title ? (
+    <h2 className="debo:text-lg debo:font-semibold debo:text-base-content debo:pb-2 debo:mb-4 debo:border-b debo:border-base-300">
+      {title}
+    </h2>
+  ) : null;
+
+  if (loading) return <>{heading}<DeboLoading /></>;
+
+  if (error) {
+    return (
+      <>
+        {heading}
+        <DeboAlert type="error" className="debo:font-sans debo:my-4">
+          <svg xmlns="http://www.w3.org/2000/svg" className="debo:h-5 debo:w-5 debo:shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M10 14l2-2m0 0l2-2m-2 2l-2-2m2 2l2 2m7-2a9 9 0 11-18 0 9 9 0 0118 0z" />
+          </svg>
+          <span>Failed to load data: {error}</span>
+        </DeboAlert>
+      </>
+    );
+  }
+
+  if (!data) {
+    const empty = (
+      <>
+        {heading}
+        <DeboEmptyState
+          message={emptyMessage}
+          command={command}
+          filePath={displayPath}
+        />
+      </>
+    );
+    return bare ? empty : <DeboPageLayout gap="8">{empty}</DeboPageLayout>;
+  }
+
+  if (bare) {
+    return <>{heading}{renderContent(data)}</>;
+  }
+
+  return (
+    <DeboPageLayout>
+      {heading}
+      {renderContent(data)}
+      <DeboSourceFooter path={displayPath} onReload={reload} />
+      <span className="debo:text-base-content/30 debo:text-xs debo:leading-loose">
+        Update with <code className="debo:text-base-content/40">{command}</code>
+      </span>
+    </DeboPageLayout>
+  );
+}

package/dist/components/Panel.tsx

@@ -0,0 +1,64 @@
+import React, { memo } from 'react';
+import { AddonPanel } from 'storybook/internal/components';
+import { styled } from 'storybook/theming';
+
+interface PanelProps {
+  active?: boolean;
+}
+
+const Container = styled.div(({ theme }) => ({
+  padding: '1rem',
+  fontFamily: theme.typography.fonts.base,
+  fontSize: theme.typography.size.s2,
+}));
+
+const Title = styled.h3(({ theme }) => ({
+  marginTop: 0,
+  marginBottom: '0.5rem',
+  fontWeight: theme.typography.weight.bold,
+}));
+
+const List = styled.ul({
+  listStyleType: 'none',
+  padding: 0,
+  margin: 0,
+});
+
+const Item = styled.li(({ theme }) => ({
+  padding: '0.5rem 0',
+  borderBottom: `1px solid ${theme.appBorderColor}`,
+}));
+
+const Command = styled.code(({ theme }) => ({
+  background: theme.background.hoverable,
+  padding: '0.2em 0.4em',
+  borderRadius: '4px',
+  fontFamily: theme.typography.fonts.mono,
+}));
+
+export const Panel: React.FC<PanelProps> = memo(function DesignbookPanel(props: PanelProps) {
+  return (
+    <AddonPanel active={props.active ?? false}>
+      <Container>
+        <Title>Designbook Active</Title>
+        <p>Use AI commands in your editor to interact with Designbook.</p>
+
+        <Title style={{ marginTop: '1rem' }}>Available Commands</Title>
+        <List>
+          <Item>
+            <Command>/debo-product-vision</Command> - Define product vision
+          </Item>
+          <Item>
+            <Command>/debo-product-roadmap</Command> - Create roadmap
+          </Item>
+          <Item>
+            <Command>/debo-data-model</Command> - Define data model
+          </Item>
+          <Item>
+            <Command>/debo-design-tokens</Command> - Design-Tokens document
+          </Item>
+        </List>
+      </Container>
+    </AddonPanel>
+  );
+});

package/dist/components/Tool.tsx

@@ -0,0 +1,34 @@
+import React, { memo, useCallback, useEffect } from 'react';
+import { useGlobals, type API } from 'storybook/manager-api';
+import { IconButton } from 'storybook/internal/components';
+import { ADDON_ID, KEY, TOOL_ID } from '../constants';
+import { LightningIcon } from '@storybook/icons';
+
+export const Tool = memo(function MyAddonSelector({ api }: { api: API }) {
+  const [globals, updateGlobals, storyGlobals] = useGlobals();
+
+  const isLocked = KEY in storyGlobals;
+  const isActive = !!globals[KEY];
+
+  const toggle = useCallback(() => {
+    updateGlobals({
+      [KEY]: !isActive,
+    });
+  }, [isActive]);
+
+  useEffect(() => {
+    api.setAddonShortcut(ADDON_ID, {
+      label: 'Toggle Measure [O]',
+      defaultShortcut: ['O'],
+      actionName: 'outline',
+      showInMenu: false,
+      action: toggle,
+    });
+  }, [toggle, api]);
+
+  return (
+    <IconButton key={TOOL_ID} active={isActive} disabled={isLocked} title="Enable my addon" onClick={toggle}>
+      <LightningIcon />
+    </IconButton>
+  );
+});

package/dist/components/designbookApi.js

@@ -0,0 +1,68 @@
+/**
+ * designbookApi — Low-level fetch helpers for the /__designbook/load middleware.
+ *
+ * These functions handle the middleware protocol (JSON wrapping, exists checks)
+ * exactly once. All other code should use these instead of raw fetch().
+ */
+
+const ENDPOINT = '/__designbook/load';
+
+/**
+ * Fetch a file from the designbook middleware. Returns the raw content string,
+ * or null if the file does not exist.
+ *
+ * @param {string} path — Relative path within designbook/ (e.g. "product/product-overview.md")
+ * @returns {Promise<string|null>}
+ */
+export async function loadDesignbookFile(path) {
+  try {
+    // eslint-disable-next-line no-undef
+    const res = await fetch(`${ENDPOINT}?path=${encodeURIComponent(path)}`);
+    if (!res.ok) return null;
+
+    const text = await res.text();
+    try {
+      const json = JSON.parse(text);
+      if (json.exists === false) return null;
+      if (json.content != null) return json.content;
+      // It's actual JSON data returned as a JSON response
+      return text;
+    } catch {
+      // Not JSON — plain text response
+      return text;
+    }
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fetch and parse a JSON file from the designbook middleware.
+ * Returns the parsed object, or null if the file does not exist or is invalid.
+ *
+ * @param {string} path — Relative path within designbook/ (e.g. "sections/blog/data.json")
+ * @returns {Promise<object|null>}
+ */
+export async function loadDesignbookJson(path) {
+  const raw = await loadDesignbookFile(path);
+  if (raw == null) return null;
+
+  try {
+    // If loadDesignbookFile already returned the raw JSON string,
+    // or a JSON-wrapped content string, parse it
+    return typeof raw === 'string' ? JSON.parse(raw) : raw;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if a file exists via the designbook middleware.
+ *
+ * @param {string} path — Relative path within designbook/
+ * @returns {Promise<boolean>}
+ */
+export async function designbookFileExists(path) {
+  const result = await loadDesignbookFile(path);
+  return result != null;
+}

package/dist/components/display/DeboDataModel.jsx

@@ -0,0 +1,67 @@
+
+import { DeboCollapsible } from '../ui/DeboCollapsible.jsx';
+import { DeboAlert } from '../ui/DeboAlert.jsx';
+
+function BundleSummary({ name, bundle }) {
+    const fieldCount = bundle.fields ? Object.keys(bundle.fields).length : 0;
+    return (
+        <div className="debo:mb-2 debo:last:mb-0">
+            <div className="debo:flex debo:justify-between debo:text-sm">
+                <span className="debo:font-medium debo:text-base-content">{name}</span>
+                <span className="debo:badge debo:badge-ghost debo:badge-sm">{fieldCount} fields</span>
+            </div>
+            {bundle.description && (
+                <p className="debo:text-xs debo:text-base-content/40 debo:mt-0.5">{bundle.description}</p>
+            )}
+        </div>
+    );
+}
+
+function EntityGroup({ type, bundles }) {
+    const bundleEntries = Object.entries(bundles || {});
+
+    if (bundleEntries.length === 0) return null;
+
+    const content = (
+        <div className="debo:pl-2 debo:space-y-2">
+            {bundleEntries.map(([key, def]) => (
+                <BundleSummary key={key} name={def.title || key} bundle={def} />
+            ))}
+        </div>
+    );
+
+    return (
+        <DeboCollapsible title={type} count={bundleEntries.length} defaultOpen={true}>
+            {content}
+        </DeboCollapsible>
+    );
+}
+
+/**
+ * DeboDataModel — Displays the data model definition with entity groups.
+ *
+ * @param {Object} props
+ * @param {Object} props.data - Data model data with content property
+ */
+export function DeboDataModel({ data }) {
+    if (!data || !data.content) return null;
+
+    const content = data.content;
+    const entityTypes = Object.entries(content);
+
+    return (
+        <div>
+            <DeboAlert className="debo:mb-4">
+                <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" className="debo:h-5 debo:w-5 debo:shrink-0 debo:stroke-info">
+                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
+                </svg>
+                <span className="debo:text-sm"><strong>Read Only:</strong> Run <kbd className="debo:kbd debo:kbd-sm">/debo-data-model</kbd> to make changes.</span>
+            </DeboAlert>
+            <div className="debo:space-y-2">
+                {entityTypes.map(([type, bundles]) => (
+                    <EntityGroup key={type} type={type} bundles={bundles} />
+                ))}
+            </div>
+        </div>
+    );
+}