@kubex/zinc 1.0.25 → 1.0.99

package/.claude/project.md

@@ -0,0 +1,556 @@
+# Zinc - Web Component UI Framework
+
+## Project Overview
+
+Zinc is a comprehensive web component library built on Lit that provides 93+ pre-built, accessible, and themeable UI components for modern web applications. It's designed to accelerate development by providing production-ready components that follow web standards.
+
+**Language:** TypeScript 5.3.3
+**Framework:** Lit 2.7.6 (Web Components)
+**Foundation:** Based on Shoelace components
+**Current Version:** 1.0.45
+**Documentation:** https://zinc.style
+
+## Role in the Platform
+
+Zinc is the **UI component library** of the Kubex platform:
+
+- **Rubix Integration:** Rubix uses zinc-go (Go version) for backend rendering and the Zinc web components for frontend
+- **Standalone Usage:** Can be used independently in any web application
+- **Component Prefix:** All components use the `zn-` prefix (e.g., `<zn-button>`, `<zn-input>`)
+- **Documentation Site:** https://zinc.style provides comprehensive component documentation
+
+```
+Application HTML → Zinc Components → Web Components API → Browser
+                         ↓
+                   zinc-go (Server-side rendering)
+                         ↓
+                   Rubix Console (Integration)
+```
+
+## Architecture
+
+### Core Architecture Pattern
+
+```
+┌─────────────────────────────────────────┐
+│         Application Layer               │
+│  (HTML with <zn-*> custom elements)     │
+└────────────────┬────────────────────────┘
+                 │
+┌────────────────▼────────────────────────┐
+│      Zinc Autoloader (Discovery)        │
+│  - Watches DOM for undefined elements   │
+│  - Lazy-loads components on demand      │
+└────────────────┬────────────────────────┘
+                 │
+┌────────────────▼────────────────────────┐
+│         Component Layer (93+)           │
+│  - Button, Input, DataTable, etc.       │
+│  - All extend ZincElement               │
+└────────────────┬────────────────────────┘
+                 │
+┌────────────────▼────────────────────────┐
+│      ZincElement (Base Class)           │
+│  - Extends LitElement                   │
+│  - Theme Controller                     │
+│  - Custom event system                  │
+│  - Form integration                     │
+└────────────────┬────────────────────────┘
+                 │
+┌────────────────▼────────────────────────┐
+│    Internal Services & Utilities        │
+│  - Form validation                      │
+│  - Slot detection                       │
+│  - Event system                         │
+│  - Animation registry                   │
+└─────────────────────────────────────────┘
+```
+
+### Key Directories
+
+```
+/zinc
+├── src/
+│   ├── zinc.ts                      # Main entry point (exports all 93+ components)
+│   ├── zinc-autoloader.ts           # Auto-discovery and lazy-loading system
+│   ├── components/                  # 93+ Web Components
+│   │   ├── button/
+│   │   │   ├── button.component.ts  # Component logic
+│   │   │   ├── button.scss          # Component styles
+│   │   │   ├── button.test.ts       # Component tests
+│   │   │   └── index.ts             # Exports
+│   │   ├── data-table/              # Complex table component
+│   │   ├── input/                   # Form input component
+│   │   ├── select/                  # Dropdown select
+│   │   ├── dialog/                  # Modal dialogs
+│   │   ├── editor/                  # Rich text editor (Quill)
+│   │   ├── chart/                   # Charts (ApexCharts)
+│   │   └── ... (85+ more)
+│   ├── internal/                    # Core infrastructure
+│   │   ├── zinc-element.ts          # Base class for all components
+│   │   ├── form.ts                  # Form control integration
+│   │   ├── event.ts                 # Type-safe event system
+│   │   ├── animate.ts               # Animation utilities
+│   │   ├── slot.ts                  # Slot detection controller
+│   │   └── watch.ts                 # Property watchers
+│   ├── events/                      # Event definitions (38+ event types)
+│   │   ├── events.ts                # Barrel file
+│   │   ├── zn-change.ts
+│   │   ├── zn-input.ts
+│   │   └── ... (one per event type)
+│   ├── utilities/                   # Helper functions
+│   │   ├── on.ts                    # Event listeners
+│   │   ├── query.ts                 # DOM querying
+│   │   ├── base-path.ts             # Asset resolution
+│   │   └── localize.ts              # i18n
+│   └── translations/                # i18n data
+├── scss/                            # Global styles and themes
+│   ├── themes/
+│   │   ├── _light.scss              # Light theme variables
+│   │   └── _dark.scss               # Dark theme variables
+│   ├── shared/                      # Global styles
+│   │   ├── _base.scss
+│   │   ├── _reset.scss
+│   │   └── _form-elements.scss
+│   ├── variables/                   # Design tokens
+│   ├── mixins/                      # SCSS mixins
+│   └── boot.scss                    # Bootstrap stylesheet
+├── docs/                            # 11ty-powered documentation site
+│   ├── pages/
+│   │   ├── index.md                 # Homepage
+│   │   ├── getting-started/         # Installation guides
+│   │   └── components/              # Component docs (85+ pages)
+│   ├── _includes/                   # Nunjucks templates
+│   │   ├── component.njk            # Component doc template
+│   │   └── default.njk              # Default layout
+│   ├── _utilities/                  # Build utilities
+│   │   ├── markdown.cjs             # Custom markdown renderer
+│   │   └── code-previews.cjs        # Live code preview system
+│   ├── eleventy.config.cjs          # 11ty configuration
+│   └── assets/                      # Static assets
+├── dist/                            # Built outputs
+│   ├── zinc.js                      # Main ES module
+│   ├── zinc.min.js                  # Minified version
+│   ├── custom-elements.json         # Component metadata
+│   └── web-types.json               # IDE support
+├── scripts/
+│   └── build.js                     # Custom esbuild pipeline
+├── package.json                     # Project metadata (v1.0.45)
+├── tsconfig.json                    # TypeScript config
+└── custom-elements-manifest.config.js  # Metadata generation
+```
+
+## Key Technologies
+
+### Core Dependencies
+- **lit** (2.7.6) - Reactive web components library
+- **@lit-labs/observers** - Observe changes in templates
+- **@lit/task** - Task management for async operations
+- **@floating-ui/dom** - Positioning for dropdowns, tooltips
+- **@shoelace-style/localize** - Internationalization
+
+### Advanced Components
+- **apexcharts** (4.5.0) - Charting library
+- **chart.js** (4.4.8) - Alternative charting
+- **quill** (2.0.3) - Rich text editor
+- **emoji-mart** - Emoji picker
+- **air-datepicker** (3.5.3) - Date picker
+
+### Build Tools
+- **esbuild** (0.25.0) - Fast JavaScript bundler
+- **sass** (1.85.1) - CSS preprocessor
+- **typescript** (5.3.3) - Type checking
+- **@11ty/eleventy** - Documentation site generator
+- **@web/test-runner** - Component testing
+
+## Component Categories (93+ Total)
+
+### Form Components (15+)
+Input, Textarea, Select, Checkbox, Radio, Toggle, Datepicker, File, Rating, ColorPicker, Range, etc.
+
+### Data Display (10+)
+DataTable, Chart, SimpleChart, Stat, ProgressBar, ProgressTile, Skeleton, Timeline, etc.
+
+### Navigation (8+)
+Button, ButtonGroup, Navbar, Sidebar, Tabs, Pagination, Stepper, VerticalStepper
+
+### Dialogs & Overlays (8+)
+Dialog, Popup, Tooltip, Dropdown, Slideout, Confirm, Alert, Drawer
+
+### Layout (8+)
+Cols, Pane, SplitPane, ScrollContainer, AbsoluteContainer, HoverContainer, FlexContainer
+
+### Content (8+)
+Tile, TileProperty, Note, EmptyState, Header, ContentBlock, Card, Well
+
+### Tables & Advanced (5+)
+OrderTable, DataTableFilter, DataTableSort, BulkActions, QueryBuilder
+
+### Utilities (15+)
+Icon, Key, Chip, Badge, Avatar, Spinner, Divider, Menu, MenuItem, etc.
+
+## Component Anatomy
+
+### Standard Component Structure
+```typescript
+// Example: src/components/button/button.component.ts
+import { html, unsafeCSS } from 'lit';
+import { property, query } from 'lit/decorators.js';
+import ZincElement from '../../internal/zinc-element';
+import styles from './button.scss';
+
+export default class ZnButton extends ZincElement {
+  static styles = unsafeCSS(styles);
+  static dependencies = { 'zn-icon': ZnIcon };
+
+  @property() color: 'default' | 'primary' | 'error' = 'default';
+  @property({type: Boolean}) disabled = false;
+  @query('.button') button: HTMLButtonElement;
+
+  protected render() {
+    return html`<button part="base" ...>...</button>`;
+  }
+
+  // Custom event emission with type safety
+  handleClick() {
+    this.emit('zn-click', { detail: { ... } });
+  }
+}
+
+// Auto-register component
+ZnButton.define('zn-button');
+```
+
+### Component Features
+- **Shadow DOM:** Encapsulated styles
+- **CSS Parts:** Exposed for external styling
+- **Slots:** Flexible content projection
+- **Events:** Type-safe custom events
+- **Form Integration:** Native HTML form support
+- **Accessibility:** ARIA attributes and keyboard navigation
+- **Theming:** CSS custom properties
+
+## Auto-Discovery System
+
+### Lazy Loading
+```typescript
+// zinc-autoloader.ts provides dynamic component discovery
+export async function discover(root: Element | ShadowRoot) {
+  // Find all undefined <zn-*> elements
+  const tags = [...root.querySelectorAll(':not(:defined)')]
+    .map(el => el.tagName.toLowerCase())
+    .filter(tag => tag.startsWith('zn-'));
+
+  // Auto-import and register them
+  await Promise.allSettled(tagsToRegister.map(tagName => register(tagName)));
+}
+
+// Watches for new elements added to DOM
+observer.observe(document.documentElement, {subtree: true, childList: true});
+```
+
+**Benefits:**
+- Components lazy-loaded only when used
+- Reduces initial bundle size
+- Works with dynamic HTML injection
+- No manual component imports needed
+
+## Form Integration
+
+### FormControlController
+Provides standardized form integration:
+- Native HTML `<form>` element integration
+- Constraint validation API
+- User interaction tracking for validation state
+- Form attributes: `name`, `value`, `disabled`, `required`, etc.
+
+### Example Form Component
+```html
+<form id="myForm">
+  <zn-input name="username" label="Username" required></zn-input>
+  <zn-input name="email" type="email" label="Email" required></zn-input>
+  <zn-button type="submit">Submit</zn-button>
+</form>
+
+<script>
+  document.getElementById('myForm').addEventListener('submit', (e) => {
+    e.preventDefault();
+    const formData = new FormData(e.target);
+    console.log(Object.fromEntries(formData));
+  });
+</script>
+```
+
+## Theming System
+
+### CSS Custom Properties
+Light and dark themes controlled via CSS variables:
+
+```scss
+// Light theme (_light.scss)
+:root {
+  --color-primary: #0066cc;
+  --color-background: #ffffff;
+  --spacing-m: 1rem;
+  --border-radius: 4px;
+  // ... 100+ design tokens
+}
+
+// Dark theme (_dark.scss)
+:root[data-theme="dark"] {
+  --color-primary: #4da6ff;
+  --color-background: #1a1a1a;
+  // ... dark variants
+}
+```
+
+### Theme Variables
+- **Colors:** Primary, secondary, success, warning, error, info
+- **Spacing:** xs, s, m, l, xl
+- **Typography:** Font families, sizes, weights
+- **Borders:** Widths, radius
+- **Shadows:** Elevation levels
+
+## Documentation Site (https://zinc.style)
+
+### Technology Stack
+- **11ty (Eleventy)** - Static site generator
+- **Nunjucks** - Templating language
+- **Lunr** - Client-side search
+- **PrismJS** - Syntax highlighting
+- **Custom Markdown** - Extended markdown for live previews
+
+### Key Features
+1. **Live Component Previews** - Markdown syntax for interactive demos
+2. **Component Documentation** - One page per component
+3. **Auto-generated Metadata** - Props/slots/events from source
+4. **Searchable** - Full-text search via Lunr
+5. **Responsive Design** - Mobile-first
+6. **Theme Switching** - Dark/light mode
+
+### Documentation Build
+```bash
+cd docs
+npm install
+npm run build  # Builds to _site/
+npm run serve  # Development server
+```
+
+## Development
+
+### Running Locally
+```bash
+# Install dependencies
+npm install
+
+# Build components
+npm run build
+
+# Watch mode (rebuild on changes)
+npm run watch
+
+# Run tests
+npm run test
+
+# Lint code
+npm run lint
+
+# Build documentation
+cd docs && npm run build
+```
+
+### Creating a New Component
+
+1. **Create component directory:**
+```bash
+mkdir src/components/my-component
+```
+
+2. **Create component files:**
+```
+my-component/
+├── my-component.component.ts  # Component logic
+├── my-component.scss          # Component styles
+├── my-component.test.ts       # Tests
+└── index.ts                   # Exports
+```
+
+3. **Implement component:**
+```typescript
+import { html, unsafeCSS } from 'lit';
+import { property } from 'lit/decorators.js';
+import ZincElement from '../../internal/zinc-element';
+import styles from './my-component.scss';
+
+export default class ZnMyComponent extends ZincElement {
+  static styles = unsafeCSS(styles);
+
+  @property() label = '';
+
+  render() {
+    return html`<div part="base">${this.label}</div>`;
+  }
+}
+
+ZnMyComponent.define('zn-my-component');
+```
+
+4. **Export from zinc.ts:**
+```typescript
+export { default as ZnMyComponent } from './components/my-component';
+```
+
+5. **Create documentation:**
+```markdown
+<!-- docs/pages/components/my-component.md -->
+---
+title: My Component
+description: Component description
+---
+
+# My Component
+
+Usage examples...
+```
+
+## Build Process
+
+### Custom Build Pipeline (`scripts/build.js`)
+1. Clean previous builds
+2. Compile SCSS to CSS (PostCSS/autoprefixer)
+3. Bundle TypeScript (esbuild)
+4. Generate custom-elements-manifest
+5. Minify outputs
+6. Build documentation (11ty)
+
+### Distribution Outputs
+- `dist/zinc.js` - ES module export
+- `dist/zinc.min.js` - Minified version
+- `dist/custom-elements.json` - Component metadata
+- `dist/web-types.json` - IDE support
+- `docs/_site/` - Static documentation site
+
+## Usage in Applications
+
+### Installation
+```bash
+npm install @kubex/zinc
+```
+
+### Import All Components
+```javascript
+import '@kubex/zinc/dist/zinc.js';
+```
+
+### Import Specific Components
+```javascript
+import '@kubex/zinc/dist/components/button/button.js';
+import '@kubex/zinc/dist/components/input/input.js';
+```
+
+### Use Auto-loader
+```javascript
+import '@kubex/zinc/dist/zinc-autoloader.js';
+// Components auto-load when used in HTML
+```
+
+### HTML Usage
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="node_modules/@kubex/zinc/dist/themes/light.css">
+  <script type="module" src="node_modules/@kubex/zinc/dist/zinc-autoloader.js"></script>
+</head>
+<body>
+  <zn-button color="primary">Click Me</zn-button>
+  <zn-input label="Username" required></zn-input>
+  <zn-data-table id="myTable"></zn-data-table>
+
+  <script>
+    const table = document.getElementById('myTable');
+    table.data = [
+      { name: 'John', age: 30 },
+      { name: 'Jane', age: 25 }
+    ];
+  </script>
+</body>
+</html>
+```
+
+## Integration Points
+
+### With Rubix
+- **zinc-go:** Go version of Zinc for backend rendering
+- **Static Console:** Rubix console uses Zinc web components
+- **Component Library:** Shared component library across platform
+
+### Standalone Usage
+- Can be used in any web application
+- Framework-agnostic (works with React, Vue, Angular, vanilla JS)
+- Progressive enhancement (works without JavaScript for basic functionality)
+
+## Testing
+
+### Component Tests
+```bash
+npm run test
+npm run test:watch  # Watch mode
+```
+
+### Testing Framework
+- **@web/test-runner** - Test runner
+- **Playwright** - Browser automation
+- **Chai** - Assertions
+
+### Example Test
+```typescript
+import { expect, fixture, html } from '@open-wc/testing';
+import type ZnButton from './button.component';
+
+describe('ZnButton', () => {
+  it('renders with default properties', async () => {
+    const el = await fixture<ZnButton>(html`<zn-button>Click</zn-button>`);
+    expect(el.color).to.equal('default');
+    expect(el.disabled).to.be.false;
+  });
+
+  it('emits click event', async () => {
+    const el = await fixture<ZnButton>(html`<zn-button>Click</zn-button>`);
+    let clicked = false;
+    el.addEventListener('zn-click', () => clicked = true);
+    el.click();
+    expect(clicked).to.be.true;
+  });
+});
+```
+
+## Performance Considerations
+
+- **Lazy Loading:** Components load on demand via autoloader
+- **Tree Shaking:** Import only components you use
+- **Shadow DOM:** Encapsulated styles prevent global pollution
+- **Virtual Scrolling:** DataTable uses virtual scrolling for large datasets
+- **Debouncing:** Input components debounce events
+- **Memoization:** Expensive computations cached
+
+## Accessibility
+
+- **ARIA Labels:** All components have proper ARIA attributes
+- **Keyboard Navigation:** Full keyboard support
+- **Focus Management:** Proper focus indicators and trap
+- **Screen Reader Support:** Semantic HTML and ARIA
+- **ESLint Rules:** lit-a11y plugin enforces accessibility
+
+## Related Repositories
+
+- **rubix** - Uses Zinc for frontend console interface
+- **zinc-go** - Go version of Zinc for backend rendering
+- **zinc-php** - PHP version of Zinc for backend rendering
+
+## Resources
+
+- **Documentation:** https://zinc.style
+- **Component API:** See custom-elements.json in dist/
+- **Examples:** See docs/pages/components/ for live examples
+- **Contributing:** Follow TypeScript strict mode and ESLint rules

package/.github/workflows/js_build_and_deploy.yaml

@@ -11,12 +11,12 @@ jobs:
       - uses: actions/checkout@v3 # Check out the repository
 
       - name: Setup Node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
-          node-version: '20.x'
+          node-version: '24'
 
       - name: Cache npm
-        uses: actions/cache@v3
+        uses: actions/cache@v5
         with:
           path: ~/.npm
           key: ${{ runner.os }}-node-${{ hashFiles('**/package.json') }}
@@ -26,7 +26,7 @@ jobs:
       - run: npm run build # Build the site
 
       # Store the dist folder
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: app-build
           path: dist
@@ -36,9 +36,10 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
+      id-token: write  # Required for OIDC
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -47,9 +48,9 @@ jobs:
         uses: justincy/github-action-npm-release@2.0.2
 
         # Setup .npmrc file to publish to npm
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
-          node-version: '20.x'
+          node-version: '24'
           registry-url: 'https://registry.npmjs.org'
 
         # Get the dist folder
@@ -59,7 +60,5 @@ jobs:
           name: app-build
           path: dist
 
-      - run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - run: npm publish --access public --provenance