@tessera-ui/core 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Kenneth Guidaven
+
+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,225 @@
+# Tessera UI
+
+A framework-agnostic web component library built with **Stencil.js** and **TypeScript**. Write components once, use them everywhere — React, Vue, Angular, or vanilla HTML.
+
+**[Documentation](https://jkguidaven.github.io/tessera-ui/)** | **[Storybook](https://jkguidaven.github.io/tessera-ui/storybook/)** | **[npm](https://www.npmjs.com/package/@tessera-ui/core)**
+
+## Features
+
+- **Framework agnostic** — Web Components that work in any framework or none
+- **Auto-generated bindings** — First-class React, Vue, and Angular wrappers via Stencil output targets
+- **Design tokens** — Full theming via CSS custom properties (works through Shadow DOM)
+- **Dark mode** — Built-in dark theme support via `data-theme="dark"`
+- **Accessible** — WCAG 2.1 AA compliant, keyboard navigable, ARIA patterns
+- **TypeScript** — Strict mode, fully typed props, events, and public methods
+- **Tree-shakeable** — Import only the components you use
+
+## Quick Start
+
+### Install
+
+```bash
+# Core Web Components
+npm install @tessera-ui/core
+
+# Framework-specific wrappers (pick one)
+npm install @tessera-ui/react
+npm install @tessera-ui/vue
+npm install @tessera-ui/angular
+```
+
+### Usage: Vanilla HTML
+
+```html
+<script type="module" src="https://unpkg.com/@tessera-ui/core/dist/tessera-ui/tessera-ui.esm.js"></script>
+
+<ts-button variant="primary" size="lg">Get Started</ts-button>
+<ts-input label="Email" type="email" placeholder="you@example.com"></ts-input>
+<ts-badge variant="success" pill>Active</ts-badge>
+```
+
+### Usage: React
+
+```tsx
+import { TsButton, TsInput } from '@tessera-ui/react';
+
+function App() {
+  return (
+    <div>
+      <TsButton variant="primary" onTsClick={() => console.log('clicked!')}>
+        Submit
+      </TsButton>
+      <TsInput label="Name" onTsInput={(e) => console.log(e.detail.value)} />
+    </div>
+  );
+}
+```
+
+### Usage: Vue
+
+```vue
+<template>
+  <ts-button variant="primary" @tsClick="handleClick">Submit</ts-button>
+  <ts-input label="Name" @tsInput="handleInput" />
+</template>
+
+<script setup>
+import { TsButton, TsInput } from '@tessera-ui/vue';
+
+const handleClick = () => console.log('clicked!');
+const handleInput = (e) => console.log(e.detail.value);
+</script>
+```
+
+### Usage: Angular
+
+```typescript
+import { TesseraUIModule } from '@tessera-ui/angular';
+
+@NgModule({
+  imports: [TesseraUIModule],
+})
+export class AppModule {}
+```
+
+```html
+<ts-button variant="primary" (tsClick)="onClick()">Submit</ts-button>
+<ts-input label="Name" (tsInput)="onInput($event)"></ts-input>
+```
+
+## Components
+
+| Component      | Tag            | Description                              |
+| -------------- | -------------- | ---------------------------------------- |
+| Button         | `<ts-button>`   | Actions with variants, sizes, states     |
+| Input          | `<ts-input>`    | Text input with validation & labels      |
+| Card           | `<ts-card>`     | Content container with elevation/slots   |
+| Modal          | `<ts-modal>`    | Dialog with focus trapping & a11y        |
+| Badge          | `<ts-badge>`    | Status indicators & labels               |
+| Toggle         | `<ts-toggle>`   | Switch control for boolean values        |
+| Alert          | `<ts-alert>`    | Contextual feedback messages             |
+| Tooltip        | `<ts-tooltip>`  | Hover/focus information popups           |
+
+## Theming
+
+Tessera UI uses CSS custom properties for theming. Override tokens on `:root` or any container:
+
+```css
+:root {
+  --ts-color-primary-500: #e63946;
+  --ts-color-primary-600: #d62839;
+  --ts-radius-md: 12px;
+  --ts-font-family-base: 'Outfit', sans-serif;
+}
+```
+
+Enable dark mode by adding `data-theme="dark"` to any ancestor element.
+
+## Theming
+
+Tessera UI uses a **three-tier token architecture** for maximum flexibility:
+
+| Tier | Prefix | Purpose |
+|---|---|---|
+| Reference | `--ts-ref-*` | Raw palette values (never use directly) |
+| Semantic | `--ts-*` | Role-based tokens (what components consume) |
+| Component | `--ts-{component}-*` | Per-component overrides (customization API) |
+
+Override component tokens to customize individual components without touching the design system:
+
+```css
+/* Customize all buttons */
+ts-button {
+  --ts-button-radius: 9999px;
+}
+
+/* Customize all cards */
+ts-card {
+  --ts-card-bg: #f0f0f0;
+  --ts-card-radius: 0;
+}
+```
+
+Or override semantic tokens to change the entire system:
+
+```css
+:root {
+  --ts-color-interactive-primary: #e63946;
+  --ts-color-interactive-primary-hover: #c1121f;
+}
+```
+
+## Documentation
+
+- **Docs site** — `https://jkguidaven.github.io/tessera-ui/` — component API reference, design tokens, getting started guides. Deployed on **release**.
+- **Storybook** — `https://jkguidaven.github.io/tessera-ui/storybook/` — interactive component playground. Deployed on **release** alongside docs.
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start dev server with hot reload (Stencil watch + Storybook)
+pnpm start
+
+# Run unit tests
+pnpm test
+
+# Run E2E tests
+pnpm test.e2e
+
+# Build for production
+pnpm build
+
+# Build docs site locally
+pnpm build && pnpm -C docs build
+```
+
+## Releasing
+
+Tessera UI uses [Lerna](https://lerna.js.org/) with fixed versioning — all packages share the same version.
+
+### 1. Bump versions
+
+```bash
+pnpm version:bump          # Lerna bumps all package versions and creates a commit + tag
+```
+
+### 2. Push and create a GitHub Release
+
+```bash
+git push && git push --tags
+```
+
+Then create a [GitHub Release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) from the new tag. This triggers the release workflow which:
+
+1. **Publishes to npm** — all `@tessera-ui/*` packages (`core`, `react`, `vue`, `angular`)
+2. Builds the component library
+3. Builds Storybook
+4. Generates and builds the documentation site with the release version
+5. Deploys docs + Storybook to GitHub Pages
+
+### CI Setup (required once)
+
+The npm publish job requires an `NPM_TOKEN` secret in the GitHub repository settings:
+
+1. Create the `tessera-ui` org at [npmjs.com/org/create](https://www.npmjs.com/org/create)
+2. Generate an **Automation** token at [npmjs.com/settings/~/tokens](https://www.npmjs.com/settings/~/tokens)
+3. Add it as `NPM_TOKEN` under **Settings → Secrets and variables → Actions**
+
+## Architecture
+
+```
+Author (Stencil + TypeScript)
+     ↓ compile
+Web Components (Custom Elements + Shadow DOM)
+     ↓ output targets
+┌────────────┬────────────┬──────────────┬────────────┐
+│ dist (ESM) │ React pkg  │   Vue pkg    │ Angular pkg│
+└────────────┴────────────┴──────────────┴────────────┘
+```
+
+## License
+
+MIT

package/dist/cjs/aria-CeYIvz3U.js

@@ -0,0 +1,94 @@
+'use strict';
+
+/**
+ * Tessera UI — Accessibility Utilities
+ *
+ * Helpers for consistent ARIA patterns across components.
+ */
+/** Generate a unique ID for ARIA relationships */
+let idCounter = 0;
+function generateId(prefix = 'q') {
+    idCounter += 1;
+    return `${prefix}-${idCounter}`;
+}
+/**
+ * Announce a message to screen readers via a live region.
+ * Creates a temporary `aria-live` element, inserts the message,
+ * and removes it after the AT has time to read it.
+ */
+function announce(message, priority = 'polite') {
+    const el = document.createElement('div');
+    el.setAttribute('aria-live', priority);
+    el.setAttribute('role', 'status');
+    el.setAttribute('aria-atomic', 'true');
+    Object.assign(el.style, {
+        position: 'absolute',
+        width: '1px',
+        height: '1px',
+        padding: '0',
+        margin: '-1px',
+        overflow: 'hidden',
+        clip: 'rect(0, 0, 0, 0)',
+        whiteSpace: 'nowrap',
+        border: '0',
+    });
+    document.body.appendChild(el);
+    // Delay to ensure the live region is registered before content is added
+    requestAnimationFrame(() => {
+        el.textContent = message;
+        setTimeout(() => el.remove(), 1000);
+    });
+}
+/**
+ * Check if the user prefers reduced motion.
+ */
+function prefersReducedMotion() {
+    return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+/**
+ * Trap focus within a container element.
+ * Returns a cleanup function to remove the trap.
+ */
+function trapFocus(container) {
+    const focusableSelectors = [
+        'a[href]',
+        'button:not([disabled])',
+        'input:not([disabled])',
+        'select:not([disabled])',
+        'textarea:not([disabled])',
+        '[tabindex]:not([tabindex="-1"])',
+    ].join(', ');
+    function handleKeydown(event) {
+        if (event.key !== 'Tab')
+            return;
+        const focusableElements = Array.from(container.querySelectorAll(focusableSelectors));
+        if (focusableElements.length === 0) {
+            event.preventDefault();
+            return;
+        }
+        const firstFocusable = focusableElements[0];
+        const lastFocusable = focusableElements[focusableElements.length - 1];
+        if (event.shiftKey) {
+            if (document.activeElement === firstFocusable) {
+                event.preventDefault();
+                lastFocusable.focus();
+            }
+        }
+        else {
+            if (document.activeElement === lastFocusable) {
+                event.preventDefault();
+                firstFocusable.focus();
+            }
+        }
+    }
+    container.addEventListener('keydown', handleKeydown);
+    return () => container.removeEventListener('keydown', handleKeydown);
+}
+
+exports.announce = announce;
+exports.generateId = generateId;
+exports.prefersReducedMotion = prefersReducedMotion;
+exports.trapFocus = trapFocus;
+//# sourceMappingURL=aria-CeYIvz3U.js.map
+
+//# sourceMappingURL=aria-CeYIvz3U.js.map

package/dist/cjs/aria-CeYIvz3U.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aria-CeYIvz3U.js","sources":["src/utils/aria.ts"],"sourcesContent":["/**\n * Tessera UI — Accessibility Utilities\n *\n * Helpers for consistent ARIA patterns across components.\n */\n\n/** Generate a unique ID for ARIA relationships */\nlet idCounter = 0;\nexport function generateId(prefix = 'q'): string {\n  idCounter += 1;\n  return `${prefix}-${idCounter}`;\n}\n\n/** Reset ID counter (for testing) */\nexport function resetIdCounter(): void {\n  idCounter = 0;\n}\n\n/**\n * Announce a message to screen readers via a live region.\n * Creates a temporary `aria-live` element, inserts the message,\n * and removes it after the AT has time to read it.\n */\nexport function announce(message: string, priority: 'polite' | 'assertive' = 'polite'): void {\n  const el = document.createElement('div');\n  el.setAttribute('aria-live', priority);\n  el.setAttribute('role', 'status');\n  el.setAttribute('aria-atomic', 'true');\n  Object.assign(el.style, {\n    position: 'absolute',\n    width: '1px',\n    height: '1px',\n    padding: '0',\n    margin: '-1px',\n    overflow: 'hidden',\n    clip: 'rect(0, 0, 0, 0)',\n    whiteSpace: 'nowrap',\n    border: '0',\n  });\n\n  document.body.appendChild(el);\n\n  // Delay to ensure the live region is registered before content is added\n  requestAnimationFrame(() => {\n    el.textContent = message;\n    setTimeout(() => el.remove(), 1000);\n  });\n}\n\n/**\n * Check if the user prefers reduced motion.\n */\nexport function prefersReducedMotion(): boolean {\n  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;\n}\n\n/**\n * Trap focus within a container element.\n * Returns a cleanup function to remove the trap.\n */\nexport function trapFocus(container: HTMLElement): () => void {\n  const focusableSelectors = [\n    'a[href]',\n    'button:not([disabled])',\n    'input:not([disabled])',\n    'select:not([disabled])',\n    'textarea:not([disabled])',\n    '[tabindex]:not([tabindex=\"-1\"])',\n  ].join(', ');\n\n  function handleKeydown(event: KeyboardEvent): void {\n    if (event.key !== 'Tab') return;\n\n    const focusableElements = Array.from(\n      container.querySelectorAll<HTMLElement>(focusableSelectors)\n    );\n\n    if (focusableElements.length === 0) {\n      event.preventDefault();\n      return;\n    }\n\n    const firstFocusable = focusableElements[0];\n    const lastFocusable = focusableElements[focusableElements.length - 1];\n\n    if (event.shiftKey) {\n      if (document.activeElement === firstFocusable) {\n        event.preventDefault();\n        lastFocusable.focus();\n      }\n    } else {\n      if (document.activeElement === lastFocusable) {\n        event.preventDefault();\n        firstFocusable.focus();\n      }\n    }\n  }\n\n  container.addEventListener('keydown', handleKeydown);\n  return () => container.removeEventListener('keydown', handleKeydown);\n}\n"],"names":[],"mappings":";;AAAA;;;;AAIG;AAEH;AACA,IAAI,SAAS,GAAG,CAAC;AACX,SAAU,UAAU,CAAC,MAAM,GAAG,GAAG,EAAA;IACrC,SAAS,IAAI,CAAC;AACd,IAAA,OAAO,CAAA,EAAG,MAAM,CAAA,CAAA,EAAI,SAAS,EAAE;AACjC;AAOA;;;;AAIG;SACa,QAAQ,CAAC,OAAe,EAAE,WAAmC,QAAQ,EAAA;IACnF,MAAM,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC;AACxC,IAAA,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,QAAQ,CAAC;AACtC,IAAA,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC;AACjC,IAAA,EAAE,CAAC,YAAY,CAAC,aAAa,EAAE,MAAM,CAAC;AACtC,IAAA,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE;AACtB,QAAA,QAAQ,EAAE,UAAU;AACpB,QAAA,KAAK,EAAE,KAAK;AACZ,QAAA,MAAM,EAAE,KAAK;AACb,QAAA,OAAO,EAAE,GAAG;AACZ,QAAA,MAAM,EAAE,MAAM;AACd,QAAA,QAAQ,EAAE,QAAQ;AAClB,QAAA,IAAI,EAAE,kBAAkB;AACxB,QAAA,UAAU,EAAE,QAAQ;AACpB,QAAA,MAAM,EAAE,GAAG;AACZ,KAAA,CAAC;AAEF,IAAA,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;;IAG7B,qBAAqB,CAAC,MAAK;AACzB,QAAA,EAAE,CAAC,WAAW,GAAG,OAAO;QACxB,UAAU,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC;AACrC,KAAC,CAAC;AACJ;AAEA;;AAEG;SACa,oBAAoB,GAAA;IAClC,OAAO,MAAM,CAAC,UAAU,CAAC,kCAAkC,CAAC,CAAC,OAAO;AACtE;AAEA;;;AAGG;AACG,SAAU,SAAS,CAAC,SAAsB,EAAA;AAC9C,IAAA,MAAM,kBAAkB,GAAG;QACzB,SAAS;QACT,wBAAwB;QACxB,uBAAuB;QACvB,wBAAwB;QACxB,0BAA0B;QAC1B,iCAAiC;AAClC,KAAA,CAAC,IAAI,CAAC,IAAI,CAAC;IAEZ,SAAS,aAAa,CAAC,KAAoB,EAAA;AACzC,QAAA,IAAI,KAAK,CAAC,GAAG,KAAK,KAAK;YAAE;AAEzB,QAAA,MAAM,iBAAiB,GAAG,KAAK,CAAC,IAAI,CAClC,SAAS,CAAC,gBAAgB,CAAc,kBAAkB,CAAC,CAC5D;AAED,QAAA,IAAI,iBAAiB,CAAC,MAAM,KAAK,CAAC,EAAE;YAClC,KAAK,CAAC,cAAc,EAAE;YACtB;;AAGF,QAAA,MAAM,cAAc,GAAG,iBAAiB,CAAC,CAAC,CAAC;QAC3C,MAAM,aAAa,GAAG,iBAAiB,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC,CAAC;AAErE,QAAA,IAAI,KAAK,CAAC,QAAQ,EAAE;AAClB,YAAA,IAAI,QAAQ,CAAC,aAAa,KAAK,cAAc,EAAE;gBAC7C,KAAK,CAAC,cAAc,EAAE;gBACtB,aAAa,CAAC,KAAK,EAAE;;;aAElB;AACL,YAAA,IAAI,QAAQ,CAAC,aAAa,KAAK,aAAa,EAAE;gBAC5C,KAAK,CAAC,cAAc,EAAE;gBACtB,cAAc,CAAC,KAAK,EAAE;;;;AAK5B,IAAA,SAAS,CAAC,gBAAgB,CAAC,SAAS,EAAE,aAAa,CAAC;IACpD,OAAO,MAAM,SAAS,CAAC,mBAAmB,CAAC,SAAS,EAAE,aAAa,CAAC;AACtE;;;;;;;"}