@clidey/dory 1.0.8 → 1.9.0

package/docs/components/expandable.mdx

@@ -0,0 +1,189 @@
+---
+title: 'Expandable'
+description: 'Expandable sections for API response fields, nested properties, and schema documentation.'
+---
+
+# Expandable
+
+The `Expandable` component and its companion components (`ResponseField`, `Properties`, `Property`) are designed for documenting API response schemas and nested data structures.
+
+## Expandable
+
+A collapsible section with a title and optional icon:
+
+<Specimen label="&lt;Expandable&gt;">
+
+```mdx
+<Expandable title="Response Body">
+  The response includes the following fields:
+
+  - `id` — Unique identifier
+  - `name` — Display name
+  - `created_at` — ISO 8601 timestamp
+</Expandable>
+```
+
+<Expandable title="Response Body">
+  The response includes the following fields:
+
+  - `id` — Unique identifier
+  - `name` — Display name
+  - `created_at` — ISO 8601 timestamp
+</Expandable>
+
+</Specimen>
+
+## Expandable with Icon
+
+<Specimen label="&lt;Expandable&gt;">
+
+```mdx
+<Expandable title="Advanced Options" icon="settings-2">
+  These options are optional and have sensible defaults.
+
+  - `timeout` — Request timeout in milliseconds (default: `5000`)
+  - `retries` — Number of retries on failure (default: `3`)
+</Expandable>
+```
+
+<Expandable title="Advanced Options" icon="settings-2">
+  These options are optional and have sensible defaults.
+
+  - `timeout` — Request timeout in milliseconds (default: `5000`)
+  - `retries` — Number of retries on failure (default: `3`)
+</Expandable>
+
+</Specimen>
+
+## ResponseField
+
+Document a single API response field with its type and description:
+
+<Specimen label="&lt;ResponseField&gt;">
+
+```mdx
+<ResponseField name="id" type="string" required>
+  Unique identifier for the resource. Format: UUID v4.
+</ResponseField>
+
+<ResponseField name="name" type="string" required>
+  Display name of the resource. Max 255 characters.
+</ResponseField>
+
+<ResponseField name="metadata" type="object">
+  Optional key-value metadata attached to the resource.
+</ResponseField>
+
+<ResponseField name="created_at" type="string (ISO 8601)">
+  Timestamp when the resource was created.
+</ResponseField>
+```
+
+<ResponseField name="id" type="string" required>
+  Unique identifier for the resource. Format: UUID v4.
+</ResponseField>
+
+<ResponseField name="name" type="string" required>
+  Display name of the resource. Max 255 characters.
+</ResponseField>
+
+<ResponseField name="metadata" type="object">
+  Optional key-value metadata attached to the resource.
+</ResponseField>
+
+<ResponseField name="created_at" type="string (ISO 8601)">
+  Timestamp when the resource was created.
+</ResponseField>
+
+</Specimen>
+
+## Properties and Property
+
+Document a group of schema properties:
+
+<Specimen label="&lt;Properties&gt; &lt;Property&gt;">
+
+```mdx
+<Properties>
+  <Property name="user_id" type="string">
+    ID of the authenticated user making the request.
+  </Property>
+  <Property name="workspace" type="string">
+    Workspace slug. Defaults to the user's personal workspace.
+  </Property>
+  <Property name="dry_run" type="boolean">
+    If `true`, validates the request without making changes.
+  </Property>
+</Properties>
+```
+
+<Properties>
+  <Property name="user_id" type="string">
+    ID of the authenticated user making the request.
+  </Property>
+  <Property name="workspace" type="string">
+    Workspace slug. Defaults to the user's personal workspace.
+  </Property>
+  <Property name="dry_run" type="boolean">
+    If `true`, validates the request without making changes.
+  </Property>
+</Properties>
+
+</Specimen>
+
+## Nested Schema Example
+
+Combine `Expandable` with `ResponseField` and `Properties` for complex nested schemas:
+
+<Specimen label="&lt;ResponseField&gt; &lt;Expandable&gt;">
+
+```mdx
+<ResponseField name="user" type="object" required>
+  The authenticated user object.
+
+  <Expandable title="user fields">
+    <ResponseField name="user.id" type="string">UUID of the user.</ResponseField>
+    <ResponseField name="user.email" type="string">Email address.</ResponseField>
+    <ResponseField name="user.role" type="string">One of: `admin`, `editor`, `viewer`.</ResponseField>
+  </Expandable>
+</ResponseField>
+```
+
+<ResponseField name="user" type="object" required>
+  The authenticated user object.
+
+  <Expandable title="user fields">
+    <ResponseField name="user.id" type="string">UUID of the user.</ResponseField>
+    <ResponseField name="user.email" type="string">Email address.</ResponseField>
+    <ResponseField name="user.role" type="string">One of: `admin`, `editor`, `viewer`.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+</Specimen>
+
+## Props Reference
+
+### Expandable Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | Label shown when the section is collapsed. |
+| `icon` | `string` | Optional Clidey Design icon name. |
+| `children` | `ReactNode` | Content shown when expanded. |
+
+### ResponseField Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Field name (e.g. `"user_id"`). |
+| `type` | `string` | Data type (e.g. `"string"`, `"object"`, `"boolean"`). |
+| `required` | `boolean` | If true, shows a "Required" badge. |
+| `children` | `ReactNode` | Description of the field. |
+
+### Property Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Property name. |
+| `type` | `string` | Data type. |
+| `children` | `ReactNode` | Description of the property. |

package/docs/components/icons.mdx

@@ -0,0 +1,71 @@
+---
+title: 'Icons'
+description: 'The shared Clidey Design icon suite for inline content and components.'
+---
+
+# Icons
+
+The `<Icon>` component renders icons from `@clidey/ux/icons`. Icons inherit the text color unless you set `color`. Names use kebab-case.
+
+## Basic Usage
+
+<Specimen label="&lt;Icon&gt;">
+
+```mdx
+<Icon icon="promote" />
+<Icon icon="code" />
+<Icon icon="check-circle" />
+```
+
+<Icon icon="promote" /> <Icon icon="code" /> <Icon icon="check-circle" />
+
+</Specimen>
+
+## Color and Size
+
+<Specimen label="&lt;Icon&gt;">
+
+```mdx
+<Icon icon="star" color="#f59e0b" size={16} />
+<Icon icon="star" color="#f59e0b" size={24} />
+<Icon icon="star" color="#f59e0b" size={40} />
+```
+
+<Icon icon="star" color="#f59e0b" size={16} /> <Icon icon="star" color="#f59e0b" size={24} /> <Icon icon="star" color="#f59e0b" size={40} />
+
+</Specimen>
+
+## Icons in Context
+
+<Specimen label="&lt;Icon&gt;">
+
+```mdx
+<Icon icon="terminal" size={16} /> Run `dory build` to compile your site.
+
+<Icon icon="packages" size={16} /> Install with `npm install -g @clidey/dory`.
+
+<Icon icon="branch" size={16} /> Push the `dist/` directory to your hosting provider.
+```
+
+<Icon icon="terminal" size={16} /> Run `dory build` to compile your site.
+
+<Icon icon="packages" size={16} /> Install with `npm install -g @clidey/dory`.
+
+<Icon icon="branch" size={16} /> Push the `dist/` directory to your hosting provider.
+
+</Specimen>
+
+## Icon Catalog
+
+The catalog includes every icon published by Clidey Design, including distinct variants with `-alt` suffixes. Click an icon to copy its MDX tag. Existing source-prefixed names such as `enterprise/chevron-down` continue to work.
+
+<IconGrid />
+
+## Props Reference
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `icon` | `string` | — | Clidey Design icon name, such as `check-circle`. |
+| `color` | `string` | Inherits from text | CSS color value. |
+| `size` | `number` | `24` | Icon size in pixels. |
+| `className` | `string` | — | Additional CSS classes. |

package/docs/components/images.mdx

@@ -0,0 +1,82 @@
+---
+title: 'Images'
+description: 'Clickable images with fullscreen modal overlay using the img component.'
+---
+
+# Images
+
+Images in Dory support click-to-fullscreen functionality. Clicking any image opens it in a fullscreen modal overlay with a dark background.
+
+## Basic Usage
+
+Use standard Markdown image syntax:
+
+<Specimen label="![alt](src)">
+
+```mdx
+![Dory logo](../assets/dory.jpeg)
+```
+
+![Dory logo](../assets/dory.jpeg)
+
+</Specimen>
+
+## HTML img Tag
+
+You can also use the HTML `<img>` tag for more control:
+
+<Specimen label="&lt;img&gt;">
+
+```mdx
+<img src="../assets/dory.jpeg" alt="Dory logo" className="w-32 h-32 object-cover rounded" />
+```
+
+<img src="../assets/dory.jpeg" alt="Dory logo" className="w-32 h-32 object-cover rounded" />
+
+</Specimen>
+
+## Fullscreen Behavior
+
+When a user clicks an image:
+1. A fullscreen overlay appears with a black semi-transparent background
+2. The image is displayed centered at full size
+3. Clicking anywhere on the overlay closes it
+
+This is useful for screenshots, diagrams, and any image where detail matters.
+
+## Images in Columns
+
+Images can be combined with `<Row>` and `<Col>` for side-by-side layouts:
+
+```mdx
+<Row>
+  <Col>
+    **Light Mode**
+
+    ![Light mode](../assets/light-mode.png)
+  </Col>
+  <Col>
+    **Dark Mode**
+
+    ![Dark mode](../assets/dark-mode.png)
+  </Col>
+</Row>
+```
+
+## Best Practices
+
+<Note>
+  Store images in the `assets/` directory inside your docs folder. Reference them with paths relative to the MDX file, as your editor previews them (e.g. `../assets/image.png` from a page in `components/`). Dory rewrites relative paths to site-root paths at build time, so they work on every page and host. Root paths such as `/assets/image.png` also work.
+</Note>
+
+<Tip>
+  Use SVG images where possible — they scale perfectly at any size and the fullscreen mode will display them at full resolution without any blurriness.
+</Tip>
+
+## Props
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `src` | `string` | Image URL or path. |
+| `alt` | `string` | Alt text for accessibility. |
+| `className` | `string` | CSS classes for sizing and styling. |

package/docs/components/latex.mdx

@@ -0,0 +1,148 @@
+---
+title: 'LaTeX Math'
+description: 'Render mathematical expressions and equations using KaTeX with the Latex component.'
+---
+
+# LaTeX Math
+
+The `<Latex>` component renders mathematical expressions using [KaTeX](https://katex.org). Use it for equations, formulas, and any mathematical notation.
+
+<Note>
+  In MDX, curly braces inside JSX content are parsed as JavaScript expressions. For LaTeX expressions containing curly braces (like `\frac{a}{b}`), use a JavaScript string literal: `{'\\frac{a}{b}'}`.
+</Note>
+
+## Basic Expressions
+
+Simple expressions without curly braces work directly:
+
+<Specimen label="&lt;Latex&gt;">
+
+```mdx
+<Row cols={2}>
+  <Col><Latex>E = mc^2</Latex></Col>
+  <Col><Latex>a^2 + b^2 = c^2</Latex></Col>
+</Row>
+
+Inline math sits in the sentence: sorting the index costs <Latex inline>O(n \log n)</Latex> comparisons.
+```
+
+<Row cols={2} className="py-0">
+  <Col><Latex>E = mc^2</Latex></Col>
+  <Col><Latex>a^2 + b^2 = c^2</Latex></Col>
+</Row>
+
+Inline math sits in the sentence: sorting the index costs <Latex inline>O(n \log n)</Latex> comparisons.
+
+<SpecimenProps>
+
+<Prop name="children" type="string">LaTeX expression.</Prop>
+<Prop name="inline" type="boolean">Render inline with the text instead of as a display tile. Default: `false`.</Prop>
+
+</SpecimenProps>
+
+</Specimen>
+
+## Fractions and Derivatives
+
+For LaTeX with curly braces, wrap in a JS string literal:
+
+<Specimen label="&lt;Latex&gt;">
+
+```mdx
+<Latex>{'\\frac{d}{dx}\\left(\\int_0^x f(t)\\,dt\\right) = f(x)'}</Latex>
+```
+
+<Latex>{'\\frac{d}{dx}\\left(\\int_0^x f(t)\\,dt\\right) = f(x)'}</Latex>
+
+</Specimen>
+
+<Specimen label="&lt;Latex&gt;">
+
+```mdx
+<Latex>{'x = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}'}</Latex>
+```
+
+<Latex>{'x = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}'}</Latex>
+
+</Specimen>
+
+## Summation
+
+<Specimen label="&lt;Latex&gt;">
+
+```mdx
+<Latex>{'\\sum_{i=1}^{n} i = \\frac{n(n+1)}{2}'}</Latex>
+```
+
+<Latex>{'\\sum_{i=1}^{n} i = \\frac{n(n+1)}{2}'}</Latex>
+
+</Specimen>
+
+## Integrals
+
+<Specimen label="&lt;Latex&gt;">
+
+```mdx
+<Latex>{'\\int_{-\\infty}^{\\infty} e^{-x^2}\\,dx = \\sqrt{\\pi}'}</Latex>
+```
+
+<Latex>{'\\int_{-\\infty}^{\\infty} e^{-x^2}\\,dx = \\sqrt{\\pi}'}</Latex>
+
+</Specimen>
+
+## Normal Distribution
+
+<Specimen label="&lt;Latex&gt;">
+
+```mdx
+<Latex>{'f(x) = \\frac{1}{\\sigma\\sqrt{2\\pi}}e^{-\\frac{(x-\\mu)^2}{2\\sigma^2}}'}</Latex>
+```
+
+<Latex>{'f(x) = \\frac{1}{\\sigma\\sqrt{2\\pi}}e^{-\\frac{(x-\\mu)^2}{2\\sigma^2}}'}</Latex>
+
+</Specimen>
+
+## Euler's Identity
+
+<Specimen label="&lt;Latex&gt;">
+
+```mdx
+<Latex>e^{i\pi} + 1 = 0</Latex>
+```
+
+<Latex>{'e^{i\\pi} + 1 = 0'}</Latex>
+
+</Specimen>
+
+## Using Strings vs Direct Content
+
+<Row>
+  <Col>
+    **Direct content (works for simple expressions)**
+
+    ```mdx
+    <Latex>a^2 + b^2 = c^2</Latex>
+    ```
+
+    Works when the expression has no `{` or `}` characters.
+  </Col>
+  <Col>
+    **String literal (required for complex expressions)**
+
+    ```mdx
+    <Latex>{'\\frac{a}{b}'}</Latex>
+    ```
+
+    Required when the expression contains `{...}` braces. Use `\\` for backslashes in the string.
+  </Col>
+</Row>
+
+## Props Reference
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `children` | `string` | LaTeX expression string. |
+
+<Note>
+  KaTeX supports a large subset of LaTeX. See the [KaTeX supported functions](https://katex.org/docs/supported) documentation for the complete list.
+</Note>

package/docs/components/layout.mdx

@@ -0,0 +1,175 @@
+---
+title: 'Layout'
+description: 'Row and Col components for multi-column grid layouts within MDX pages.'
+---
+
+# Layout
+
+The `<Row>` and `<Col>` components create responsive multi-column layouts inside your MDX content.
+
+## Basic Two-Column Layout
+
+<Specimen label="&lt;Row&gt; &lt;Col&gt;">
+
+```mdx
+<Row>
+  <Col>
+    Left column content here.
+  </Col>
+  <Col>
+    Right column content here.
+  </Col>
+</Row>
+```
+
+<Row>
+  <Col>
+    **Left column**
+
+    Content on the left side. Columns are equal width by default.
+  </Col>
+  <Col>
+    **Right column**
+
+    Content on the right side.
+  </Col>
+</Row>
+
+</Specimen>
+
+## Prose + Code Pattern
+
+The most common layout: prose on the left, a sticky code column on the right.
+Use `sticky` on the code column so it stays visible while the prose scrolls.
+
+<Specimen label="&lt;Row&gt; &lt;Col&gt;">
+
+```mdx
+<Row>
+  <Col>
+    ## Creating a user
+
+    Send a POST request to /api/users with the user's name and email.
+
+    ### Required fields
+
+    - `name` — Display name (max 255 characters)
+    - `email` — Valid email address
+  </Col>
+  <Col sticky>
+    Request and response examples here.
+  </Col>
+</Row>
+```
+
+<Row>
+  <Col>
+    ## Creating a user
+
+    Send a `POST` request to `/api/users` with the user's name and email.
+
+    The response includes the new user's `id`, which you'll need for subsequent requests.
+
+    ### Required fields
+
+    - `name` — Display name (max 255 characters)
+    - `email` — Valid email address (must be unique)
+  </Col>
+  <Col sticky>
+    **Request**
+
+    `POST /api/users`
+
+    `Content-Type: application/json`
+
+    **Response**
+
+    `201 Created`
+  </Col>
+</Row>
+
+</Specimen>
+
+## Three Columns
+
+<Specimen label="&lt;Row&gt; &lt;Col&gt;">
+
+```mdx
+<Row cols={3}>
+  <Col>Column 1</Col>
+  <Col>Column 2</Col>
+  <Col>Column 3</Col>
+</Row>
+```
+
+<Row cols={3}>
+  <Col>
+    **Column 1**
+
+    First piece of content.
+  </Col>
+  <Col>
+    **Column 2**
+
+    Second piece of content.
+  </Col>
+  <Col>
+    **Column 3**
+
+    Third piece of content.
+  </Col>
+</Row>
+
+</Specimen>
+
+## Specimen
+
+`<Specimen>` frames a component example with **Preview**, **Code** and **Props** tabs. Put the MDX source in an ` ```mdx ` fence, the rendered example after it, and optional `<Prop>` rows inside `<SpecimenProps>`. Tabs only appear for the parts you include.
+
+<Specimen label="&lt;Specimen&gt; &lt;SpecimenProps&gt;">
+
+`````mdx
+<Specimen label="&lt;Tag&gt;">
+
+````mdx
+<Tag color="sky">Beta</Tag>
+````
+
+<Tag color="sky">Beta</Tag>
+
+<SpecimenProps>
+<Prop name="color" type="string">Badge color.</Prop>
+</SpecimenProps>
+
+</Specimen>
+`````
+
+<Tag color="sky">Beta</Tag>
+
+<SpecimenProps>
+
+<Prop name="label" type="string">Mono caption in the header, usually the component tag. Write angle brackets as `&lt;` and `&gt;`.</Prop>
+<Prop name="children" type="ReactNode">An ` ```mdx ` fence (Code tab), a `<SpecimenProps>` block (Props tab), and the preview.</Prop>
+
+</SpecimenProps>
+
+</Specimen>
+
+## Props Reference
+
+### Row Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `cols` | `number` | `1` | Grid column count. |
+| `className` | `string` | — | Additional CSS classes. |
+| `children` | `ReactNode` | — | `Col` components. |
+
+### Col Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `sticky` | `boolean` | `false` | Enables `xl:sticky top-24` positioning. Keeps the column visible while adjacent content scrolls. |
+| `rows` | `number` | `1` | Number of CSS grid rows this column spans. |
+| `gap` | `number` | `4` | Spacing (Tailwind scale) between items inside the column. |
+| `children` | `ReactNode` | — | Column content. |