@frontmcp/ui 0.5.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,438 @@
+# @frontmcp/ui
+
+Platform-agnostic HTML component library for building authentication and authorization UIs across LLM platforms.
+
+## Features
+
+- **Pure HTML Output** - No React, Vue, or JSX dependencies. Components return HTML strings.
+- **Zod Validation** - All component options validated at runtime with detailed error feedback.
+- **Platform-Aware** - Optimized for OpenAI, Claude, Gemini, and ngrok platforms.
+- **HTMX Support** - Built-in support for dynamic interactions without JavaScript.
+- **Theme System** - Customizable themes with CDN URL configuration.
+- **GitHub/OpenAI Theme** - Default gray-black aesthetic inspired by GitHub and OpenAI.
+
+## Installation
+
+```bash
+npm install @frontmcp/ui
+# or
+yarn add @frontmcp/ui
+```
+
+## Quick Start
+
+```typescript
+import { button, card, baseLayout, DEFAULT_THEME } from '@frontmcp/ui';
+
+// Create a simple button
+const btn = button('Click Me', { variant: 'primary', size: 'md' });
+
+// Create a card with content
+const content = card(
+  `
+  <h2>Welcome</h2>
+  <p>Hello, world!</p>
+`,
+  { variant: 'default' },
+);
+
+// Wrap in a page layout
+const page = baseLayout(content, {
+  title: 'My Page',
+  theme: DEFAULT_THEME,
+});
+```
+
+## Components
+
+### Button
+
+```typescript
+import { button, primaryButton, dangerButton, buttonGroup } from '@frontmcp/ui';
+
+// Basic button
+button('Submit');
+
+// Button variants
+button('Save', { variant: 'secondary' });
+button('Delete', { variant: 'danger' });
+button('Cancel', { variant: 'outline' });
+
+// Shorthand functions
+primaryButton('Submit');
+dangerButton('Delete');
+
+// Button with HTMX
+button('Load More', {
+  htmx: {
+    get: '/api/items?page=2',
+    target: '#items-list',
+    swap: 'beforeend',
+  },
+});
+
+// Button group
+buttonGroup([button('Edit', { variant: 'outline' }), button('Delete', { variant: 'danger' })], { attached: true });
+```
+
+### Card
+
+```typescript
+import { card, cardGroup } from '@frontmcp/ui';
+
+// Basic card
+card('<p>Card content</p>');
+
+// Card with title and footer
+card('<p>Content</p>', {
+  title: 'Card Title',
+  subtitle: 'Optional subtitle',
+  footer: '<button>Action</button>',
+  variant: 'elevated',
+});
+
+// Card group
+cardGroup([card('Card 1', { title: 'First' }), card('Card 2', { title: 'Second' })], { columns: 2 });
+```
+
+### Form Components
+
+```typescript
+import { form, input, select, textarea, checkbox, radioGroup, formRow, formActions } from '@frontmcp/ui';
+
+// Complete form
+form(
+  `
+  ${input({ name: 'email', type: 'email', label: 'Email Address', required: true })}
+  ${input({ name: 'password', type: 'password', label: 'Password', required: true })}
+  ${checkbox({ name: 'remember', label: 'Remember me' })}
+  ${formActions(button('Sign In', { type: 'submit' }))}
+`,
+  {
+    action: '/login',
+    method: 'post',
+    htmx: { post: '/api/login', target: '#result' },
+  },
+);
+
+// Select dropdown
+select({
+  name: 'country',
+  label: 'Country',
+  options: [
+    { value: 'us', label: 'United States' },
+    { value: 'uk', label: 'United Kingdom' },
+  ],
+});
+
+// Radio group
+radioGroup({
+  name: 'plan',
+  label: 'Select Plan',
+  options: [
+    { value: 'free', label: 'Free' },
+    { value: 'pro', label: 'Pro' },
+  ],
+});
+```
+
+### Alert & Badge
+
+```typescript
+import { alert, successAlert, warningAlert, badge, activeBadge } from '@frontmcp/ui';
+
+// Alerts
+alert('Information message', { variant: 'info' });
+successAlert('Operation completed!');
+warningAlert('Please review your input.');
+
+// Badges
+badge('New');
+badge('Active', { variant: 'success' });
+activeBadge(); // Green "Active" badge
+```
+
+### Modal & Drawer
+
+```typescript
+import { modal, modalTrigger, drawer, confirmModal } from '@frontmcp/ui';
+
+// Basic modal
+modal('<p>Modal content</p>', {
+  id: 'my-modal',
+  title: 'Modal Title',
+  size: 'md',
+});
+
+// Modal trigger button
+modalTrigger({ targetId: 'my-modal', text: 'Open Modal' });
+
+// Confirmation modal
+confirmModal({
+  id: 'delete-confirm',
+  title: 'Confirm Delete',
+  message: 'Are you sure you want to delete this item?',
+  variant: 'danger',
+  onConfirm: { delete: '/api/items/123' },
+});
+
+// Drawer
+drawer('<nav>Navigation</nav>', {
+  id: 'nav-drawer',
+  position: 'left',
+  title: 'Menu',
+});
+```
+
+### Table & Pagination
+
+```typescript
+import { table, pagination } from '@frontmcp/ui';
+
+// Data table
+const data = [
+  { id: 1, name: 'John', email: 'john@example.com' },
+  { id: 2, name: 'Jane', email: 'jane@example.com' },
+];
+
+table(data, {
+  columns: [
+    { key: 'id', header: 'ID', width: '60px' },
+    { key: 'name', header: 'Name', sortable: true },
+    { key: 'email', header: 'Email' },
+  ],
+  selectable: true,
+  hoverable: true,
+});
+
+// Pagination
+pagination({
+  page: 1,
+  totalPages: 10,
+  htmx: { get: '/api/items?page={page}', target: '#table' },
+});
+```
+
+## Theme System
+
+### Using the Default Theme
+
+```typescript
+import { DEFAULT_THEME, GITHUB_OPENAI_THEME, baseLayout } from '@frontmcp/ui';
+
+// DEFAULT_THEME is the GitHub/OpenAI gray-black theme
+const page = baseLayout(content, {
+  theme: DEFAULT_THEME,
+});
+```
+
+### Creating Custom Themes
+
+```typescript
+import { createTheme } from '@frontmcp/ui';
+
+const myTheme = createTheme({
+  name: 'my-brand',
+  colors: {
+    semantic: {
+      primary: '#0969da',
+      secondary: '#8250df',
+      accent: '#bf8700',
+    },
+  },
+  typography: {
+    families: {
+      sans: '"Roboto", system-ui, sans-serif',
+    },
+  },
+  cdn: {
+    fonts: {
+      stylesheets: ['https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&display=swap'],
+    },
+  },
+});
+```
+
+### Theme CDN Configuration
+
+Customize external resource URLs for compliance or self-hosting:
+
+```typescript
+const theme = createTheme({
+  cdn: {
+    fonts: {
+      preconnect: ['https://fonts.example.com'],
+      stylesheets: ['https://fonts.example.com/css/roboto.css'],
+    },
+    scripts: {
+      tailwind: 'https://cdn.example.com/tailwind.js',
+      htmx: {
+        url: 'https://cdn.example.com/htmx.min.js',
+        integrity: 'sha512-...',
+      },
+    },
+    icons: {
+      script: { url: 'https://cdn.example.com/lucide.min.js' },
+    },
+  },
+});
+```
+
+## Platform Support
+
+### Platform Detection
+
+```typescript
+import { getPlatform, canUseCdn, needsInlineScripts } from '@frontmcp/ui';
+
+const platform = getPlatform('openai');
+
+if (canUseCdn(platform)) {
+  // Use external CDN scripts
+} else if (needsInlineScripts(platform)) {
+  // Embed scripts inline for blocked-network platforms
+}
+```
+
+### Building for Specific Platforms
+
+```typescript
+import { buildCdnScriptsFromTheme, fetchAndCacheScriptsFromTheme, DEFAULT_THEME } from '@frontmcp/ui';
+
+// For OpenAI, Gemini, ngrok (open network)
+const scripts = buildCdnScriptsFromTheme(DEFAULT_THEME);
+
+// For Claude Artifacts (blocked network)
+await fetchAndCacheScriptsFromTheme(DEFAULT_THEME);
+const inlineScripts = buildCdnScriptsFromTheme(DEFAULT_THEME, { inline: true });
+```
+
+## Validation
+
+All components validate their options using Zod schemas. Invalid inputs render an error box instead of crashing:
+
+```typescript
+// Valid - renders button
+button('Click', { variant: 'primary' });
+
+// Invalid - renders error box showing "button" component and "variant" param
+button('Click', { variant: 'invalid' as any });
+
+// Unknown properties rejected (strict mode)
+button('Click', { unknownProp: true } as any);
+```
+
+### Using Schemas Directly
+
+```typescript
+import { ButtonOptionsSchema } from '@frontmcp/ui';
+
+// Validate before passing to component
+const result = ButtonOptionsSchema.safeParse(userInput);
+if (result.success) {
+  button('Click', result.data);
+} else {
+  console.error('Validation errors:', result.error.issues);
+}
+```
+
+## Layouts
+
+### Base Layout
+
+```typescript
+import { baseLayout } from '@frontmcp/ui';
+
+const html = baseLayout(content, {
+  title: 'Page Title',
+  description: 'Page description for SEO',
+  theme: DEFAULT_THEME,
+  width: 'md', // 'sm' | 'md' | 'lg' | 'xl' | 'full'
+  align: 'center', // 'left' | 'center' | 'right'
+  scripts: { htmx: true, tailwind: true },
+});
+```
+
+## Testing Tool UI
+
+When using `@frontmcp/ui` components in Tool UI templates (React, MDX), you can use `@frontmcp/testing` for E2E validation:
+
+```typescript
+import { test, expect, UIAssertions } from '@frontmcp/testing';
+
+test.describe('Tool UI with @frontmcp/ui', () => {
+  test('renders UI components correctly', async ({ mcp }) => {
+    const result = await mcp.tools.call('my-tool', { data: 'test' });
+
+    // Verify HTML is rendered (not fallback)
+    expect(result).toHaveRenderedHtml();
+    expect(result).toHaveProperHtmlStructure();
+
+    // Verify data binding
+    const output = result.json();
+    expect(result).toContainBoundValue(output.data);
+
+    // Security validation
+    expect(result).toBeXssSafe();
+
+    // Extract HTML for additional assertions
+    const html = UIAssertions.assertRenderedUI(result);
+
+    // Verify @frontmcp/ui component classes
+    expect(html).toContain('btn-primary'); // Button class
+    expect(html).toContain('card'); // Card component
+  });
+});
+```
+
+### UI Matchers
+
+| Matcher                       | Description                                     |
+| ----------------------------- | ----------------------------------------------- |
+| `toHaveRenderedHtml()`        | Checks `_meta['ui/html']` exists, not fallback  |
+| `toContainHtmlElement(tag)`   | Checks HTML contains `<tag>` element            |
+| `toContainBoundValue(value)`  | Checks output value appears in HTML             |
+| `toBeXssSafe()`               | No `<script>`, event handlers, `javascript:`    |
+| `toHaveWidgetMetadata()`      | Has platform metadata                           |
+| `toHaveCssClass(className)`   | Checks for specific CSS class                   |
+| `toNotContainRawContent(str)` | Content is NOT present (for fallback detection) |
+| `toHaveProperHtmlStructure()` | HTML has tags, not escaped text                 |
+
+### UIAssertions Helper
+
+```typescript
+import { UIAssertions } from '@frontmcp/testing';
+
+// Extract HTML from result
+const html = UIAssertions.assertRenderedUI(result);
+
+// Validate data binding
+UIAssertions.assertDataBinding(html, output, ['field1', 'field2']);
+
+// Comprehensive validation
+const html = UIAssertions.assertValidUI(result, ['field1', 'field2']);
+```
+
+See [@frontmcp/testing documentation](../testing/README.md) for full API reference.
+
+## Development
+
+### Building
+
+```bash
+yarn nx build ui
+```
+
+### Testing
+
+```bash
+yarn nx test ui
+```
+
+### Test Coverage
+
+The library maintains 95%+ test coverage across all metrics.
+
+## License
+
+MIT