datocms-react-ui 2.1.4 → 3.0.1-alpha.0

package/dist/esm/Canvas/index.d.ts

@@ -9,283 +9,188 @@ export declare type CanvasProps = {
     children: ReactNode;
 };
 /**
- * @example Color palette CSS variables
+ * @example Semantic color token CSS variables
  *
- * Within the `Canvas` component, a color palette is made available as a set of
- * CSS variables, allowing you to conform to the theme of the current
- * environment:
+ * Inside `Canvas`, the host exposes a full semantic color palette as CSS
+ * custom properties. Components should reference these tokens directly —
+ * they adapt to the user's active theme (including dark mode)
+ * automatically.
+ *
+ * ### How to read a token name
+ *
+ * ```
+ * --color--{property}                 // standalone (one -- after color)
+ * --color--{context}--{property}      // context pair (two -- after color)
+ * ```
+ *
+ * **Properties** — `surface` (backgrounds), `ink` (text/icons),
+ * `border` (1px lines), `outline` (focus rings), plus `fill` / `track`
+ * for progress bars.
+ *
+ * **Standalone** tokens work on any neutral page. **Contexts** are
+ * self-contained environments: always pair a `surface` with the `ink`,
+ * `border`, and hover states from the *same* context. Never mix — e.g.
+ * don't put `--color--primary--ink` on `--color--danger--surface`.
+ *
+ * Non-color tokens `--shadow--elevated` / `--shadow--float` /
+ * `--shadow--ambient` are ready-made `box-shadow` composites.
  *
  * ```js
  * <Canvas ctx={ctx}>
- *   <Section title="Text colors">
- *     <table>
- *       <tbody>
- *         <tr>
- *           <td>
- *             <code>--base-body-color</code>
- *           </td>
- *           <td width="30%">
- *             <div
- *               style={{
- *                 width: '30px',
- *                 height: '30px',
- *                 background: 'var(--base-body-color)',
- *               }}
- *             />
- *           </td>
+ *   <Section title="Standalone — use on any neutral page">
+ *     <table><tbody>
+ *       {[
+ *         ['--color--surface',          'Default page background'],
+ *         ['--color--surface-hover',    'Hovered row / list item'],
+ *         ['--color--surface-muted',    'Muted section / card background'],
+ *         ['--color--ink',              'Primary text'],
+ *         ['--color--ink-subtle',       'Secondary text / captions'],
+ *         ['--color--ink-hover',        'Text under hover'],
+ *         ['--color--ink-muted',        'De-emphasized text'],
+ *         ['--color--ink-placeholder',  'Input placeholder text'],
+ *         ['--color--ink-primary',      'Brand-highlighted text / icons'],
+ *         ['--color--ink-accent',       'Links / accent text'],
+ *         ['--color--ink-disabled',     'Disabled text'],
+ *         ['--color--border',           'Default 1px border'],
+ *         ['--color--border-hover',     'Border under hover'],
+ *       ].map(([t, d]) => (
+ *         <tr key={t}>
+ *           <td><code>{t}</code></td>
+ *           <td style={{ color: 'var(--color--ink-subtle)' }}>{d}</td>
+ *           <td width="40"><div style={{ width: '30px', height: '30px', background: `var(${t})`, border: '1px solid var(--color--border)' }} /></td>
  *         </tr>
- *         <tr>
- *           <td>
- *             <code>--light-body-color</code>
- *           </td>
- *           <td width="30%">
- *             <div
- *               style={{
- *                 width: '30px',
- *                 height: '30px',
- *                 background: 'var(--light-body-color)',
- *               }}
- *             />
- *           </td>
- *         </tr>
- *         <tr>
- *           <td>
- *             <code>--placeholder-body-color</code>
- *           </td>
- *           <td width="30%">
- *             <div
- *               style={{
- *                 width: '30px',
- *                 height: '30px',
- *                 background: 'var(--placeholder-body-color)',
- *               }}
- *             />
- *           </td>
- *         </tr>
- *       </tbody>
- *     </table>
+ *       ))}
+ *     </tbody></table>
  *   </Section>
- *   <Section title="UI colors">
- *     <table>
- *       <tbody>
- *         <tr>
- *           <td>
- *             <code>--light-bg-color</code>
- *           </td>
- *           <td width="30%">
- *             <div
- *               style={{
- *                 width: '30px',
- *                 height: '30px',
- *                 background: 'var(--light-bg-color)',
- *               }}
- *             />
- *           </td>
- *         </tr>
- *         <tr>
- *           <td>
- *             <code>--lighter-bg-color</code>
- *           </td>
- *           <td width="30%">
- *             <div
- *               style={{
- *                 width: '30px',
- *                 height: '30px',
- *                 background: 'var(--lighter-bg-color)',
- *               }}
- *             />
- *           </td>
- *         </tr>
- *         <tr>
- *           <td>
- *             <code>--disabled-bg-color</code>
- *           </td>
- *           <td width="30%">
- *             <div
- *               style={{
- *                 width: '30px',
- *                 height: '30px',
- *                 background: 'var(--disabled-bg-color)',
- *               }}
- *             />
- *           </td>
- *         </tr>
- *         <tr>
- *           <td>
- *             <code>--border-color</code>
- *           </td>
- *           <td width="30%">
- *             <div
- *               style={{
- *                 width: '30px',
- *                 height: '30px',
- *                 background: 'var(--border-color)',
- *               }}
- *             />
- *           </td>
- *         </tr>
- *         <tr>
- *           <td>
- *             <code>--darker-border-color</code>
- *           </td>
- *           <td width="30%">
- *             <div
- *               style={{
- *                 width: '30px',
- *                 height: '30px',
- *                 background: 'var(--darker-border-color)',
- *               }}
- *             />
- *           </td>
- *         </tr>
- *         <tr>
- *           <td>
- *             <code>--alert-color</code>
- *           </td>
- *           <td width="30%">
- *             <div
- *               style={{
- *                 width: '30px',
- *                 height: '30px',
- *                 background: 'var(--alert-color)',
- *               }}
- *             />
- *           </td>
- *         </tr>
- *         <tr>
- *           <td>
- *             <code>--warning-color</code>
- *           </td>
- *           <td width="30%">
- *             <div
- *               style={{
- *                 width: '30px',
- *                 height: '30px',
- *                 background: 'var(--warning-color)',
- *               }}
- *             />
- *           </td>
- *         </tr>
- *         <tr>
- *           <td>
- *             <code>--notice-color</code>
- *           </td>
- *           <td width="30%">
- *             <div
- *               style={{
- *                 width: '30px',
- *                 height: '30px',
- *                 background: 'var(--notice-color)',
- *               }}
- *             />
- *           </td>
- *         </tr>
- *         <tr>
- *           <td>
- *             <code>--warning-bg-color</code>
- *           </td>
- *           <td width="30%">
- *             <div
- *               style={{
- *                 width: '30px',
- *                 height: '30px',
- *                 background: 'var(--warning-bg-color)',
- *               }}
- *             />
- *           </td>
- *         </tr>
- *         <tr>
- *           <td>
- *             <code>--add-color</code>
- *           </td>
- *           <td width="30%">
- *             <div
- *               style={{
- *                 width: '30px',
- *                 height: '30px',
- *                 background: 'var(--add-color)',
- *               }}
- *             />
- *           </td>
- *         </tr>
- *         <tr>
- *           <td>
- *             <code>--remove-color</code>
- *           </td>
- *           <td width="30%">
- *             <div
- *               style={{
- *                 width: '30px',
- *                 height: '30px',
- *                 background: 'var(--remove-color)',
- *               }}
- *             />
- *           </td>
- *         </tr>
- *       </tbody>
- *     </table>
+ *
+ *   <Section title="Context: raised — modals, dropdowns, popovers">
+ *     <table><tbody>
+ *       {['--color--raised--surface', '--color--raised--surface-hover', '--color--raised--surface-active']
+ *         .map((t) => (<tr key={t}><td><code>{t}</code></td><td width="40"><div style={{ width: '30px', height: '30px', background: `var(${t})`, border: '1px solid var(--color--border)' }} /></td></tr>))}
+ *     </tbody></table>
  *   </Section>
- *   <Section title="Project-specific colors">
- *     <table>
- *       <tbody>
- *         <tr>
- *           <td>
- *             <code>--accent-color</code>
- *           </td>
- *           <td width="30%">
- *             <div
- *               style={{
- *                 width: '30px',
- *                 height: '30px',
- *                 background: 'var(--accent-color)',
- *               }}
- *             />
- *           </td>
- *         </tr>
- *         <tr>
- *           <td>
- *             <code>--primary-color</code>
- *           </td>
- *           <td width="30%">
- *             <div
- *               style={{
- *                 width: '30px',
- *                 height: '30px',
- *                 background: 'var(--primary-color)',
- *               }}
- *             />
- *           </td>
- *         </tr>
- *         <tr>
- *           <td>
- *             <code>--light-color</code>
- *           </td>
- *           <td width="30%">
- *             <div
- *               style={{
- *                 width: '30px',
- *                 height: '30px',
- *                 background: 'var(--light-color)',
- *               }}
- *             />
- *           </td>
- *         </tr>
- *         <tr>
- *           <td>
- *             <code>--dark-color</code>
- *           </td>
- *           <td width="30%">
- *             <div
- *               style={{
- *                 width: '30px',
- *                 height: '30px',
- *                 background: 'var(--dark-color)',
- *               }}
- *             />
- *           </td>
- *         </tr>
- *       </tbody>
- *     </table>
+ *
+ *   <Section title="Context: primary — main call-to-action buttons, badges, nav">
+ *     <table><tbody>
+ *       {['--color--primary--surface', '--color--primary--surface-hover', '--color--primary--surface-active', '--color--primary--surface-muted', '--color--primary--ink', '--color--primary--border']
+ *         .map((t) => (<tr key={t}><td><code>{t}</code></td><td width="40"><div style={{ width: '30px', height: '30px', background: `var(${t})`, border: '1px solid var(--color--border)' }} /></td></tr>))}
+ *     </tbody></table>
+ *   </Section>
+ *
+ *   <Section title="Context: tinted — subtle brand-tinted surfaces">
+ *     <table><tbody>
+ *       {['--color--tinted--surface', '--color--tinted--surface-hover', '--color--tinted--surface-active', '--color--tinted--ink']
+ *         .map((t) => (<tr key={t}><td><code>{t}</code></td><td width="40"><div style={{ width: '30px', height: '30px', background: `var(${t})`, border: '1px solid var(--color--border)' }} /></td></tr>))}
+ *     </tbody></table>
+ *   </Section>
+ *
+ *   <Section title="Context: accent, selected, disabled, danger, enterprise">
+ *     <table><tbody>
+ *       {['--color--accent--surface', '--color--accent--ink',
+ *         '--color--selected--surface', '--color--selected--ink', '--color--selected--border',
+ *         '--color--disabled--surface', '--color--disabled--ink',
+ *         '--color--danger--surface', '--color--danger--ink',
+ *         '--color--enterprise--surface']
+ *         .map((t) => (<tr key={t}><td><code>{t}</code></td><td width="40"><div style={{ width: '30px', height: '30px', background: `var(${t})`, border: '1px solid var(--color--border)' }} /></td></tr>))}
+ *     </tbody></table>
+ *   </Section>
+ *
+ *   <Section title="Context: focus — focus rings and outlines">
+ *     <table><tbody>
+ *       {['--color--focus--border', '--color--focus--outline']
+ *         .map((t) => (<tr key={t}><td><code>{t}</code></td><td width="40"><div style={{ width: '30px', height: '30px', background: `var(${t})`, border: '1px solid var(--color--border)' }} /></td></tr>))}
+ *     </tbody></table>
+ *   </Section>
+ *
+ *   <Section title="Feedback — validation and form states">
+ *     <table><tbody>
+ *       {['--color--feedback-fail--ink', '--color--feedback-fail--border', '--color--feedback-fail--outline',
+ *         '--color--feedback-warning--ink', '--color--feedback-warning--surface', '--color--feedback-warning--border',
+ *         '--color--feedback-success--ink', '--color--feedback-success--border']
+ *         .map((t) => (<tr key={t}><td><code>{t}</code></td><td width="40"><div style={{ width: '30px', height: '30px', background: `var(${t})`, border: '1px solid var(--color--border)' }} /></td></tr>))}
+ *     </tbody></table>
+ *   </Section>
+ *
+ *   <Section title="Context: highlight — rich text inline highlights">
+ *     <table><tbody>
+ *       {['--color--highlight--surface']
+ *         .map((t) => (<tr key={t}><td><code>{t}</code></td><td width="40"><div style={{ width: '30px', height: '30px', background: `var(${t})`, border: '1px solid var(--color--border)' }} /></td></tr>))}
+ *     </tbody></table>
+ *   </Section>
+ *
+ *   <Section title="Diffs — content versioning (added / removed / changed)">
+ *     <table><tbody>
+ *       {['--color--diff-added--surface', '--color--diff-removed--surface', '--color--diff-changed--surface',
+ *         '--color--diff-added--surface-subtle', '--color--diff-removed--surface-subtle', '--color--diff-changed--surface-subtle',
+ *         '--color--diff-added--outline-subtle', '--color--diff-removed--outline-subtle', '--color--diff-changed--outline-subtle',
+ *         '--color--diff-changed--border', '--color--diff-changed--border-negative']
+ *         .map((t) => (<tr key={t}><td><code>{t}</code></td><td width="40"><div style={{ width: '30px', height: '30px', background: `var(${t})`, border: '1px solid var(--color--border)' }} /></td></tr>))}
+ *     </tbody></table>
+ *   </Section>
+ *
+ *   <Section title="Status — publishing workflow badges (ink-only)">
+ *     <table><tbody>
+ *       {['--color--status-draft--ink', '--color--status-outdated--ink', '--color--status-published--ink']
+ *         .map((t) => (<tr key={t}><td><code>{t}</code></td><td><span style={{ color: `var(${t})`, fontWeight: 'bold' }}>Sample text</span></td></tr>))}
+ *     </tbody></table>
+ *   </Section>
+ *
+ *   <Section title="Backdrop & overlay — scrims and floating UI">
+ *     <table><tbody>
+ *       {['--color--backdrop--surface', '--color--backdrop--ink',
+ *         '--color--overlay--surface', '--color--overlay--surface-subtle', '--color--overlay--ink']
+ *         .map((t) => (<tr key={t}><td><code>{t}</code></td><td width="40"><div style={{ width: '30px', height: '30px', background: `var(${t})`, border: '1px solid var(--color--border)' }} /></td></tr>))}
+ *     </tbody></table>
+ *   </Section>
+ *
+ *   <Section title="Stacked — dark layered UI (uploaders, media players)">
+ *     <p>Stacked gives you three layers of depth (base → surface → raised) plus buttons, borders and a translucent fill. Use it when a dark inline panel needs internal hierarchy.</p>
+ *     <table><tbody>
+ *       {['--color--stacked--surface-base', '--color--stacked--surface', '--color--stacked--surface-raised',
+ *         '--color--stacked--surface-hover', '--color--stacked--surface-translucent',
+ *         '--color--stacked--surface-button', '--color--stacked--surface-button-active',
+ *         '--color--stacked--ink', '--color--stacked--ink-subtle', '--color--stacked--border']
+ *         .map((t) => (<tr key={t}><td><code>{t}</code></td><td width="40"><div style={{ width: '30px', height: '30px', background: `var(${t})`, border: '1px solid var(--color--border)' }} /></td></tr>))}
+ *     </tbody></table>
+ *   </Section>
+ *
+ *   <Section title="Progress — bar track and fill">
+ *     <table><tbody>
+ *       {['--color--progress--track', '--color--progress--fill', '--color--progress--fill-hover']
+ *         .map((t) => (<tr key={t}><td><code>{t}</code></td><td width="40"><div style={{ width: '30px', height: '30px', background: `var(${t})`, border: '1px solid var(--color--border)' }} /></td></tr>))}
+ *     </tbody></table>
+ *   </Section>
+ *
+ *   <Section title="Tooltip — small dark floating labels">
+ *     <table><tbody>
+ *       {['--color--tooltip--surface', '--color--tooltip--surface-hover', '--color--tooltip--ink', '--color--tooltip--ink-subtle']
+ *         .map((t) => (<tr key={t}><td><code>{t}</code></td><td width="40"><div style={{ width: '30px', height: '30px', background: `var(${t})`, border: '1px solid var(--color--border)' }} /></td></tr>))}
+ *     </tbody></table>
+ *   </Section>
+ *
+ *   <Section title="Code — dark code blocks, logs, error traces">
+ *     <table><tbody>
+ *       {['--color--code--surface', '--color--code--ink']
+ *         .map((t) => (<tr key={t}><td><code>{t}</code></td><td width="40"><div style={{ width: '30px', height: '30px', background: `var(${t})`, border: '1px solid var(--color--border)' }} /></td></tr>))}
+ *     </tbody></table>
+ *   </Section>
+ *
+ *   <Section title="Shadow colors and scrollbar">
+ *     <table><tbody>
+ *       {['--color--shadow-subtle', '--color--shadow', '--color--shadow-strong', '--color--scrollbar']
+ *         .map((t) => (<tr key={t}><td><code>{t}</code></td><td width="40"><div style={{ width: '30px', height: '30px', background: `var(${t})`, border: '1px solid var(--color--border)' }} /></td></tr>))}
+ *     </tbody></table>
+ *   </Section>
+ *
+ *   <Section title="Shadow composites — drop-in box-shadow values">
+ *     <div style={{ display: 'flex', gap: 'var(--spacing-l)', padding: 'var(--spacing-l)' }}>
+ *       {['--shadow--elevated', '--shadow--float', '--shadow--ambient'].map((t) => (
+ *         <div key={t} style={{ textAlign: 'center' }}>
+ *           <div style={{ width: '80px', height: '80px', background: 'var(--color--surface)', borderRadius: '4px', boxShadow: `var(${t})` }} />
+ *           <code style={{ display: 'block', marginTop: 'var(--spacing-s)', fontSize: 'var(--font-size-xs)' }}>{t}</code>
+ *         </div>
+ *       ))}
+ *     </div>
  *   </Section>
  * </Canvas>;
  * ```
@@ -418,7 +323,7 @@ export declare type CanvasProps = {
  *         <td>
  *           <div
  *             style={{
- *               background: 'var(--accent-color)',
+ *               background: 'var(--color--accent--surface)',
  *               width: 'var(--spacing-s)',
  *               height: 'var(--spacing-s)',
  *             }}
@@ -432,7 +337,7 @@ export declare type CanvasProps = {
  *         <td>
  *           <div
  *             style={{
- *               background: 'var(--accent-color)',
+ *               background: 'var(--color--accent--surface)',
  *               width: 'var(--spacing-m)',
  *               height: 'var(--spacing-m)',
  *             }}
@@ -446,7 +351,7 @@ export declare type CanvasProps = {
  *         <td>
  *           <div
  *             style={{
- *               background: 'var(--accent-color)',
+ *               background: 'var(--color--accent--surface)',
  *               width: 'var(--spacing-l)',
  *               height: 'var(--spacing-l)',
  *             }}
@@ -460,7 +365,7 @@ export declare type CanvasProps = {
  *         <td>
  *           <div
  *             style={{
- *               background: 'var(--accent-color)',
+ *               background: 'var(--color--accent--surface)',
  *               width: 'var(--spacing-xl)',
  *               height: 'var(--spacing-xl)',
  *             }}
@@ -474,7 +379,7 @@ export declare type CanvasProps = {
  *         <td>
  *           <div
  *             style={{
- *               background: 'var(--accent-color)',
+ *               background: 'var(--color--accent--surface)',
  *               width: 'var(--spacing-xxl)',
  *               height: 'var(--spacing-xxl)',
  *             }}
@@ -488,7 +393,7 @@ export declare type CanvasProps = {
  *         <td>
  *           <div
  *             style={{
- *               background: 'var(--accent-color)',
+ *               background: 'var(--color--accent--surface)',
  *               width: 'var(--spacing-xxxl)',
  *               height: 'var(--spacing-xxxl)',
  *             }}