@triptease/design-system-mcp 0.0.3

package/src/manifests/components/entries/dialog.ts

@@ -0,0 +1,77 @@
+import { ComponentManifest } from '@/manifests/components/types.js';
+import packageJson from '@/../package.json' with { type: 'json' };
+import { buildCDNUrl, buildMajorVersion } from '@/utils/buildCDNUrls.js';
+
+const version = packageJson.dependencies['@triptease/tt-dialog'];
+
+export default {
+  dialog: {
+    name: 'Dialog - Web Component',
+    description: 'Dialog component that displays content in a layer above the page',
+    ssrSafe: true,
+    element: 'tt-dialog',
+    usageGuidance: {
+      whenToUse: [
+        'User interaction is required to proceed',
+        "The task is short, self-contained or doesn't fit naturally into a page",
+        'The underlying page content should remain visible',
+        "Intentionally disrupting the user's flow is beneficial (e.g. confirmations, critical notifications)",
+      ],
+      avoid: [
+        'The content is long, complex, or scrollable (e.g. multi-step forms, detailed instructions)',
+        'The content should be shareable or linkable (prefer a dedicated page)',
+        'The information is not time-sensitive or critical (prefer toasts or inline disclosures)',
+        'The user did not initiate the interaction (unsolicited pop-ups can be frustrating)',
+      ],
+    },
+    installation: {
+      npm: [{ name: '@triptease/tt-dialog', includesTypes: true, optional: false }],
+      cdn: [
+        {
+          name: 'tt-dialog',
+          includesTypes: false,
+          optional: false,
+          pinnedVersionUrl: buildCDNUrl('tt-dialog', version),
+          pinnedMajorVersionUrl: buildCDNUrl('tt-dialog', buildMajorVersion(version)),
+          latestVersionUrl: buildCDNUrl('tt-dialog', 'latest'),
+          guidance:
+            'Prefer pinned major version URL to avoid unexpected breaking changes. Do not use latest version URL in production code.',
+        },
+      ],
+    },
+    examples: [
+      {
+        title: 'Basic usage',
+        code: `<button data-theme="primary" onclick="document.querySelector('#my-dialog').show()">
+  Open Dialog
+</button>
+<tt-dialog id="my-dialog" aria-label="Example dialog">
+  <div class="container">
+    <h2>Dialog Title</h2>
+    <p>This is a basic dialog with some content.</p>
+    <button data-theme="primary" onclick="document.querySelector('#my-dialog').hide()">
+      Close
+    </button>
+  </div>
+</tt-dialog>`,
+      },
+      {
+        title: 'With CSS custom properties',
+        description:
+          'Use CSS custom properties to customize dialog positioning:\n\n- `--dialog-left-distance`: Control the horizontal position of the dialog.',
+        code: `<button data-theme="primary" onclick="document.querySelector('#positioned-dialog').show()">
+  Open Dialog
+</button>
+<tt-dialog id="positioned-dialog" aria-label="Positioned dialog" style="--dialog-left-distance: 100px;">
+  <div class="container">
+    <h2>Custom Positioned Dialog</h2>
+    <p>This dialog has custom positioning using CSS custom properties.</p>
+    <button data-theme="primary" onclick="document.querySelector('#positioned-dialog').hide()">
+      Close
+    </button>
+  </div>
+</tt-dialog>`,
+      },
+    ],
+  },
+} satisfies ComponentManifest;

package/src/manifests/components/entries/lineChart.ts

@@ -0,0 +1,150 @@
+import { ComponentManifest } from '@/manifests/components/types.js';
+import { buildCDNUrl, buildMajorVersion } from '@/utils/buildCDNUrls.js';
+import packageJson from '@/../package.json' with { type: 'json' };
+
+const latestLineChartVersion = packageJson.dependencies['@triptease/tt-line-chart'];
+const latestDatasetVersion = packageJson.dependencies['@triptease/tt-dataset'];
+const latestDataPointVersion = packageJson.dependencies['@triptease/tt-data-point'];
+const latestHighlightVersion = packageJson.dependencies['@triptease/tt-highlight'];
+
+export default {
+  'line-chart': {
+    name: 'Line Chart - Web Component',
+    description: 'Line chart for visualizing trends over continuous data',
+    ssrSafe: true,
+    element: 'tt-line-chart',
+    usageGuidance: {
+      whenToUse: [
+        'To visualize trends along a continuous x-axis',
+        'To compare how multiple datasets for the same measure change relative to each other',
+      ],
+      avoid: [
+        'When the x-axis does not represent a continuous range (use a bar chart instead)',
+        'When there are too few data points to form a meaningful trend (use a bar chart instead)',
+        'When comparing datasets that do not have a meaningful or explainable relationship',
+      ],
+    },
+    installation: {
+      npm: [
+        { name: '@triptease/tt-line-chart', includesTypes: true, optional: false },
+        { name: '@triptease/tt-dataset', includesTypes: true, optional: false },
+        { name: '@triptease/tt-data-point', includesTypes: true, optional: false },
+        { name: '@triptease/tt-highlight', includesTypes: true, optional: true },
+      ],
+      cdn: [
+        {
+          name: 'tt-line-chart',
+          includesTypes: false,
+          optional: false,
+          pinnedVersionUrl: buildCDNUrl('tt-line-chart', latestLineChartVersion),
+          pinnedMajorVersionUrl: buildCDNUrl('tt-line-chart', buildMajorVersion(latestLineChartVersion)),
+          latestVersionUrl: buildCDNUrl('tt-line-chart', 'latest'),
+          guidance:
+            'Prefer pinned major version URL to avoid unexpected breaking changes. Do not use latest version URL in production code.',
+        },
+        {
+          name: 'tt-dataset',
+          includesTypes: false,
+          optional: false,
+          pinnedVersionUrl: buildCDNUrl('tt-dataset', latestDatasetVersion),
+          pinnedMajorVersionUrl: buildCDNUrl('tt-dataset', buildMajorVersion(latestDatasetVersion)),
+          latestVersionUrl: buildCDNUrl('tt-dataset', 'latest'),
+          guidance:
+            'Prefer pinned major version URL to avoid unexpected breaking changes. Do not use latest version URL in production code.',
+        },
+        {
+          name: 'tt-data-point',
+          includesTypes: false,
+          optional: false,
+          pinnedVersionUrl: buildCDNUrl('tt-data-point', latestDataPointVersion),
+          pinnedMajorVersionUrl: buildCDNUrl('tt-data-point', buildMajorVersion(latestDataPointVersion)),
+          latestVersionUrl: buildCDNUrl('tt-data-point', 'latest'),
+          guidance:
+            'Prefer pinned major version URL to avoid unexpected breaking changes. Do not use latest version URL in production code.',
+        },
+        {
+          name: 'tt-highlight',
+          includesTypes: false,
+          optional: true,
+          pinnedVersionUrl: buildCDNUrl('tt-highlight', latestHighlightVersion),
+          pinnedMajorVersionUrl: buildCDNUrl('tt-highlight', buildMajorVersion(latestHighlightVersion)),
+          latestVersionUrl: buildCDNUrl('tt-highlight', 'latest'),
+          guidance:
+            'Prefer pinned major version URL to avoid unexpected breaking changes. Do not use latest version URL in production code.',
+        },
+      ],
+    },
+    attributes: {
+      width: {
+        type: 'string',
+        description: 'Width of chart (any CSS value). Defaults to 100% to fill container.',
+      },
+      height: {
+        type: 'string',
+        description: 'Height of chart (any CSS value). Defaults to 100% to fill container.',
+      },
+      'x-axis-title': {
+        type: 'string',
+        description: 'Title for x-axis. Use to clarify units of measurement. Keep concise.',
+      },
+      'y-axis-title': {
+        type: 'string',
+        description: 'Title for y-axis. Use to clarify units of measurement. Keep concise.',
+      },
+      loading: {
+        type: 'boolean',
+        description: 'Show loading state while data fetches. Component handles aria-busy automatically.',
+      },
+      'hide-numbers': {
+        type: 'boolean',
+        description:
+          'Hide y-axis numbers and tooltips. Use when numbers could mislead. Removes ARIA labels, so provide trend description.',
+      },
+    },
+    examples: [
+      {
+        title: 'Basic line chart',
+        code: `import '@triptease/tt-line-chart';
+import '@triptease/tt-dataset';
+import '@triptease/tt-data-point';
+
+<tt-line-chart id="basic-chart">
+  <tt-dataset label="2024">
+    <tt-data-point label="Jan 1" value={45}></tt-data-point>
+    <tt-data-point label="Jan 2" value={48}></tt-data-point>
+    <tt-data-point label="Jan 3" value={52}></tt-data-point>
+  </tt-dataset>
+</tt-line-chart>`,
+      },
+      {
+        title: 'Multiple datasets',
+        description:
+          'Use multiple datasets to compare trends of the same measure for different groups. Limit datasets to a maximum of 4, as more datasets make the chart difficult to read and compare. The component automatically uses symbols to help identify each dataset without relying on color.',
+        code: `<tt-line-chart id="multiple-datasets" height="20rem">
+  <tt-dataset label="2025">
+    <tt-data-point label="Jan 1" value={45}></tt-data-point>
+    <tt-data-point label="Jan 2" value={48}></tt-data-point>
+  </tt-dataset>
+  <tt-dataset label="2024">
+    <tt-data-point label="Jan 1" value={42}></tt-data-point>
+    <tt-data-point label="Jan 2" value={44}></tt-data-point>
+  </tt-dataset>
+</tt-line-chart>`,
+      },
+      {
+        title: 'With highlighted regions',
+        description:
+          'Use highlighted regions to draw attention to and label significant intervals. Only use when something significant occurs that may have affected the data. Use sparingly and highlight only the most important intervals to avoid clutter. Avoid overlapping regions as this can make it difficult to see where each interval starts and ends. Do not use when displaying multiple datasets if the highlight applies to only one dataset, as users may assume it applies to all.',
+        code: `import '@triptease/tt-highlight';
+
+<tt-line-chart id="highlighted-chart" height="20rem">
+  <tt-dataset label="2025">
+    <tt-data-point label="Jan 1" value={45}></tt-data-point>
+    <tt-data-point label="Jan 2" value={48}></tt-data-point>
+  </tt-dataset>
+  <tt-highlight label="Easter Boost" from="15 Mar" to="5 Apr"></tt-highlight>
+</tt-line-chart>;`,
+      },
+    ],
+  },
+} satisfies ComponentManifest;

package/src/manifests/components/entries/numberinput.ts

@@ -0,0 +1,66 @@
+import { ComponentManifest } from '@/manifests/components/types.js';
+
+export default {
+  numberinput: {
+    name: 'Number Input',
+    description: 'Number input field with browser-provided increment/decrement controls',
+    element: "input[type='number']",
+    usageGuidance: {
+      whenToUse: [
+        'Collecting numeric data (age, quantity, price)',
+        'Values have clear min/max bounds',
+        'Users benefit from increment/decrement buttons',
+      ],
+      avoid: [
+        'Numbers containing formatting (phone numbers, credit cards - use text input)',
+        'Complex number validation needed',
+      ],
+    },
+    attributes: {
+      type: {
+        values: ['number'],
+        default: 'number',
+      },
+      'aria-invalid': {
+        type: 'boolean',
+        description:
+          'Marks input as invalid for error styling. Pair with aria-describedby to associate error messages.',
+      },
+      disabled: {
+        type: 'boolean',
+        description: 'Disables the input',
+      },
+      placeholder: {
+        type: 'string',
+        description: 'Placeholder text. Should not replace label - always provide visible label element.',
+      },
+      min: {
+        type: 'number',
+        description: 'Minimum allowed value',
+      },
+      max: {
+        type: 'number',
+        description: 'Maximum allowed value',
+      },
+      step: {
+        type: 'number',
+        description: 'Increment/decrement step size',
+      },
+    },
+    states: ['default', 'hover', 'focus', 'disabled', 'invalid'],
+    examples: [
+      {
+        title: 'Basic usage',
+        code: `<label for="hotel-count">Number of Hotels</label>
+<input id="hotel-count" type="number" />`,
+      },
+      {
+        title: 'Error state',
+        description: 'Use aria-invalid with aria-describedby to associate error messages for screen readers',
+        code: `<label for="quantity">Quantity</label>
+<input id="quantity" type="number" min="1" max="10" aria-invalid aria-describedby="quantity-error" />
+<span id="quantity-error" class="text-error">Please enter a number between 1 and 10</span>`,
+      },
+    ],
+  },
+} satisfies ComponentManifest;

package/src/manifests/components/entries/radio.ts

@@ -0,0 +1,53 @@
+import { ComponentManifest } from '@/manifests/components/types.js';
+
+export default {
+  radio: {
+    name: 'Radio',
+    description: 'Radio button for selecting exactly one option from mutually exclusive choices',
+    element: "input[type='radio']",
+    usageGuidance: {
+      whenToUse: [
+        'Only one option can be selected from a small set',
+        'All options need to be visible at once',
+        'Comparing options side-by-side is important',
+        'Default selection is recommended',
+      ],
+      avoid: [
+        'Multiple selections allowed (use checkboxes)',
+        'Long lists of options (consider select dropdown or combobox)',
+        'Immediate action expected (use toggle or button)',
+      ],
+    },
+    attributes: {
+      name: {
+        type: 'string',
+        description: 'Groups radio buttons together. All radio buttons in a group must have the same name.',
+      },
+      checked: {
+        type: 'boolean',
+        description: 'Marks radio button as selected by default. Only one radio in a group should be checked.',
+      },
+      disabled: {
+        type: 'boolean',
+        description:
+          'Disables the radio button. Can be applied to individual inputs or to parent fieldset to disable all radios.',
+      },
+    },
+    examples: [
+      {
+        title: 'Radio group',
+        description:
+          'Use fieldset and legend for grouped radio buttons. All radios must share the same name attribute.',
+        code: `<fieldset>
+  <legend>Choose a color:</legend>
+  <input type="radio" id="radio-red" name="color" value="red" />
+  <label for="radio-red">Red</label>
+  <input type="radio" id="radio-green" name="color" value="green" />
+  <label for="radio-green">Green</label>
+  <input type="radio" id="radio-blue" name="color" value="blue" />
+  <label for="radio-blue">Blue</label>
+</fieldset>`,
+      },
+    ],
+  },
+} satisfies ComponentManifest;

package/src/manifests/components/entries/select.ts

@@ -0,0 +1,24 @@
+import { ComponentManifest } from '@/manifests/components/types.js';
+
+export default {
+  select: {
+    name: 'Select Input',
+    description: 'Dropdown list for selecting a single option',
+    element: 'select',
+    usageGuidance: {
+      whenToUse: ['Selecting from a list of predefined options', 'Limited screen space'],
+      avoid: ['Multiple selections (use the Combobox webcomponent)'],
+    },
+    examples: [
+      {
+        title: 'Basic select',
+        code: `<label for="reports">Select report frequency</label>
+<select name="reports">
+  <option value="daily">Daily Report</option>
+  <option value="weekly">Weekly Report</option>
+  <option value="monthly">Monthly Report</option>
+</select>`,
+      },
+    ],
+  },
+} satisfies ComponentManifest;

package/src/manifests/components/entries/table.ts

@@ -0,0 +1,44 @@
+import { ComponentManifest } from '@/manifests/components/types.js';
+
+export default {
+  table: {
+    name: 'Table',
+    description: 'Organize and display data in rows and columns',
+    element: 'table',
+    usageGuidance: {
+      whenToUse: [
+        'Display structured data with multiple attributes',
+        'Enable comparison across data rows',
+        'Present numerical or tabular information',
+        'Show data relationships clearly',
+      ],
+      avoid: [
+        'For layout purposes (use CSS Grid or Flexbox)',
+        'When data is better visualized as a chart',
+        'For small amounts of data that could be in a list',
+        "On small screens where columns won't fit (consider alternative layouts)",
+      ],
+    },
+    examples: [
+      {
+        title: 'Basic table',
+        code: `<table>
+  <thead>
+    <tr>
+      <th>Property Name</th>
+      <th>Impressions</th>
+      <th>Revenue</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Downtown Suites</td>
+      <td>12,450</td>
+      <td>$5,760.00</td>
+    </tr>
+  </tbody>
+</table>`,
+      },
+    ],
+  },
+} satisfies ComponentManifest;

package/src/manifests/components/entries/textarea.ts

@@ -0,0 +1,56 @@
+import { ComponentManifest } from '@/manifests/components/types.js';
+
+export default {
+  textarea: {
+    name: 'Textarea',
+    description: 'Multi-line text input field',
+    element: 'textarea',
+    usageGuidance: {
+      whenToUse: [
+        'Multi-line text input (comments, descriptions, messages)',
+        'Content length is unpredictable',
+        'Users need to review text while typing',
+        'Text may contain line breaks',
+      ],
+      avoid: [
+        'Single-line input (use text input)',
+        'Formatted text needed (use rich text editor)',
+        'Very long content (consider breaking into sections)',
+      ],
+    },
+    attributes: {
+      'aria-invalid': {
+        type: 'boolean',
+        description:
+          'Marks textarea as invalid for error styling. Pair with aria-describedby to associate error messages.',
+      },
+      disabled: {
+        type: 'boolean',
+        description: 'Disables the textarea',
+      },
+      placeholder: {
+        type: 'string',
+        description: 'Placeholder text. Should not replace label - always provide visible label element.',
+      },
+      rows: {
+        type: 'number',
+        description: 'Number of visible text lines',
+      },
+    },
+    states: ['default', 'hover', 'focus', 'disabled', 'invalid'],
+    examples: [
+      {
+        title: 'Basic usage',
+        code: `<label for="about">About</label>
+<textarea id="about" rows="4"></textarea>`,
+      },
+      {
+        title: 'Error state',
+        description: 'Use aria-invalid with aria-describedby to associate error messages for screen readers',
+        code: `<label for="description">Description</label>
+<textarea id="description" rows="4" aria-invalid aria-describedby="description-error"></textarea>
+<span id="description-error" class="text-error">Description is required</span>`,
+      },
+    ],
+  },
+} satisfies ComponentManifest;

package/src/manifests/components/entries/textinput.ts

@@ -0,0 +1,55 @@
+import { ComponentManifest } from '@/manifests/components/types.js';
+
+export default {
+  textinput: {
+    name: 'Text Input',
+    description: 'Text input field for single-line text entry with automatic validation styling',
+    element: 'input',
+    usageGuidance: {
+      whenToUse: [
+        'Single-line text entry (names, email, search)',
+        'Predictable, short text length',
+        'Specific input types (email, password, tel, url)',
+      ],
+      avoid: [
+        'Multi-line text (use textarea)',
+        'Selecting from options (use select, radio, or combobox)',
+        'Pure numeric entry (consider number input)',
+      ],
+    },
+    attributes: {
+      type: {
+        values: ['text', 'email', 'password', 'tel', 'url'],
+        default: 'text',
+      },
+      'aria-invalid': {
+        type: 'boolean',
+        description:
+          'Marks input as invalid for error styling. Pair with aria-describedby to associate error messages.',
+      },
+      disabled: {
+        type: 'boolean',
+        description: 'Disables the input',
+      },
+      placeholder: {
+        type: 'string',
+        description: 'Placeholder text. Should not replace label - always provide visible label element.',
+      },
+    },
+    states: ['default', 'hover', 'focus', 'disabled', 'invalid'],
+    examples: [
+      {
+        title: 'Basic usage',
+        code: `<label for="hotel-name">Hotel Name</label>
+<input id="hotel-name" />`,
+      },
+      {
+        title: 'Error state',
+        description: 'Use aria-invalid with aria-describedby to associate error messages for screen readers',
+        code: `<label for="email">Email</label>
+<input id="email" type="email" aria-invalid aria-describedby="email-error" />
+<span id="email-error" class="text-error">Please enter a valid email address</span>`,
+      },
+    ],
+  },
+} satisfies ComponentManifest;

package/src/manifests/components/entries/toggle.ts

@@ -0,0 +1,31 @@
+import { ComponentManifest } from '@/manifests/components/types.js';
+
+export default {
+  toggle: {
+    name: 'Toggle',
+    description: 'Toggle switch for binary on/off states with immediate effect',
+    element: "input[type='checkbox'][data-theme='toggle']",
+    usageGuidance: {
+      whenToUse: ['Binary on/off states', 'Changes take effect immediately', 'System or feature settings'],
+      avoid: [
+        'Changes require saving (use checkbox in form)',
+        'More than two options exist (use radio buttons or select)',
+        "Relationship between on/off isn't clear",
+      ],
+    },
+    dataAttributes: {
+      'data-theme': {
+        type: 'enum',
+        values: ['toggle'],
+        description: "Use 'toggle' for switch style",
+      },
+    },
+    examples: [
+      {
+        title: 'Toggle switch',
+        code: `<input type="checkbox" id="weekly-parity-report" data-theme="toggle" />
+<label for="weekly-parity-report">Weekly Parity Report</label>`,
+      },
+    ],
+  },
+} satisfies ComponentManifest;

package/src/manifests/components/entries/typography.ts

@@ -0,0 +1,33 @@
+import { ComponentManifest } from '@/manifests/components/types.js';
+
+export default {
+  typography: {
+    name: 'Typography',
+    description: 'Text styling using semantic HTML elements and utility classes',
+    element: 'h1-h4, p, strong, a',
+    usageGuidance: {
+      whenToUse: [
+        'Use semantic elements (h1-h4, strong, a) for document structure and accessibility',
+        'Use utility classes (.heading-1 through .heading-4, .display, .body, .small, .strong, .text-error) when visual styling must differ from semantic meaning',
+        "Follow heading hierarchy - don't skip levels (h1 → h2 → h3, not h1 → h3)",
+        'Use <strong> for semantic importance, .strong for visual styling only',
+      ],
+      avoid: [
+        'Using heading classes for document structure (use semantic h1-h4 elements)',
+        'Skipping heading levels (breaks accessibility)',
+        'Using buttons styled as links or links styled as buttons (use correct semantic element)',
+      ],
+    },
+    classes: {
+      display: 'Largest text size for hero sections and prominent headlines',
+      'heading-1': 'h1 visual styling',
+      'heading-2': 'h2 visual styling',
+      'heading-3': 'h3 visual styling',
+      'heading-4': 'h4 visual styling',
+      body: 'Standard body text styling',
+      strong: 'Bold text styling without semantic importance',
+      small: 'Smaller text for captions, helper text, fine print',
+      'text-error': 'Error text color for validation messages',
+    },
+  },
+} satisfies ComponentManifest;

package/src/manifests/components/index.ts

@@ -0,0 +1,41 @@
+import type { ComponentManifest } from './types.js';
+
+import button from '@/manifests/components/entries/button.js';
+import textinput from '@/manifests/components/entries/textinput.js';
+import numberinput from '@/manifests/components/entries/numberinput.js';
+import textarea from '@/manifests/components/entries/textarea.js';
+import select from '@/manifests/components/entries/select.js';
+import checkbox from '@/manifests/components/entries/checkbox.js';
+import radio from '@/manifests/components/entries/radio.js';
+import toggle from '@/manifests/components/entries/toggle.js';
+import badge from '@/manifests/components/entries/badge.js';
+import card from '@/manifests/components/entries/card.js';
+import table from '@/manifests/components/entries/table.js';
+import typography from '@/manifests/components/entries/typography.js';
+import dialog from '@/manifests/components/entries/dialog.js';
+import combobox from '@/manifests/components/entries/combobox.js';
+import datePicker from '@/manifests/components/entries/datePicker.js';
+import dateRangePicker from '@/manifests/components/entries/dateRangePicker.js';
+import barChart from '@/manifests/components/entries/barChart.js';
+import lineChart from '@/manifests/components/entries/lineChart.js';
+
+export const componentManifest: ComponentManifest = {
+  ...button,
+  ...textinput,
+  ...numberinput,
+  ...textarea,
+  ...select,
+  ...checkbox,
+  ...radio,
+  ...toggle,
+  ...badge,
+  ...card,
+  ...table,
+  ...typography,
+  ...dialog,
+  ...combobox,
+  ...datePicker,
+  ...dateRangePicker,
+  ...barChart,
+  ...lineChart,
+};