@skewedaspect/sleekspace-ui 0.8.1 → 0.9.0

package/docs/guides/pure-css/custom-elements.md

@@ -0,0 +1,574 @@
+---
+title: Custom-Element API Reference
+description: Attribute-driven styling for Sleekspace container components using custom HTML tags — no JavaScript or element registration required.
+---
+
+# Custom-Element API Reference
+
+Sleekspace's CSS includes attribute selectors for all 19 in-scope container components, so
+you can author them as custom elements (`<sk-panel kind="primary">`) and get the exact same
+styling as the class API (`<div class="sk-panel sk-primary">`) — no JavaScript required, no
+custom-element registration, no `customElements.define()`.
+
+Browsers parse unknown tags as `HTMLUnknownElement` with `display: inline` by default.
+Sleekspace's CSS resets those to `display: block` (or `inline-flex` for badge-like components)
+so the layout behaves the same as the class-API `<div>` counterparts.
+
+## How it works
+
+The SCSS uses a dual-selector mixin that emits class and attribute selectors in the same rule:
+
+```scss
+/* Generated output — kind="primary" triggers the same rule as .sk-primary */
+.sk-panel.sk-primary,
+sk-panel[kind="primary"] { … }
+```
+
+Boolean attributes work the same way:
+
+```scss
+.sk-panel.sk-no-border,
+sk-panel[no-border] { … }
+```
+
+No JS. No polyfill. Just CSS.
+
+## Which components have a custom-element form?
+
+The 19 container components listed below all support the `<sk-*>` tag form.
+
+The following 12 components **do not** have a custom-element form and are class-API only:
+Button, Input, Textarea, Select, Slider, ColorPicker, Checkbox, Radio, Switch, NumberInput,
+TagsInput, Dropdown.
+
+**Why?** Form controls are native semantic elements with mandatory tag names (`<input>`,
+`<select>`, etc.). Replacing them with `<sk-input>` would lose native form behavior,
+accessibility, and browser autofill. Compound controls (Checkbox, Radio, Switch, NumberInput)
+require a hidden native `<input>` child that can't be expressed in a single custom tag without
+JS registration. For these 12, use the [class API](./class-api.md).
+
+---
+
+## Component Reference
+
+### sk-panel
+
+**Tag:** `<sk-panel>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `kind` | neutral, primary, accent, info, success, warning, danger, boulder, neon-blue, neon-green, neon-red, neon-yellow | neutral |
+| `size` | xs, sm, md, lg, xl | md |
+| `corners` | Space-separated: top-left, top-right, bottom-right, bottom-left | bottom-right |
+| `decoration-corner` | top-left, top-right, bottom-right, bottom-left | bottom-right |
+| `no-border` | Boolean presence | off |
+| `no-decoration` | Boolean presence | off |
+
+**Example:**
+
+```html
+<sk-panel kind="primary" size="lg" corners="top-left bottom-right" decoration-corner="top-left">
+    <p>Content here.</p>
+</sk-panel>
+```
+
+[See Vue docs →](/components/panel)
+
+---
+
+### sk-card
+
+**Tag:** `<sk-card>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `kind` | neutral, primary, accent, info, success, warning, danger | neutral |
+
+**Example:**
+
+```html
+<sk-card kind="accent">
+    <div class="sk-card-header"><h3>Card Title</h3></div>
+    <div class="sk-card-body"><p>Content.</p></div>
+</sk-card>
+```
+
+[See Vue docs →](/components/card)
+
+---
+
+### sk-alert
+
+**Tag:** `<sk-alert>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `kind` | neutral, primary, accent, info, success, warning, danger | info |
+| `subtle` | Boolean presence | off |
+
+Add `role="alert"` for accessibility. Note: the custom-element form does not auto-inject
+icon or content wrapper divs — the static helper and Vue component do that. For the full
+icon + content structure, use the static helper `alert()` or the class API form with manual
+wrapper divs (see [class API → Alert](./class-api.md#alert)).
+
+**Example:**
+
+```html
+<sk-alert kind="warning" role="alert">
+    <div class="sk-alert-content">
+        <p>Unsaved changes will be lost.</p>
+    </div>
+</sk-alert>
+```
+
+[See Vue docs →](/components/alert)
+
+---
+
+### sk-divider
+
+**Tag:** `<sk-divider>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `kind` | neutral, primary, accent, info, success, warning, danger | neutral |
+| `orientation` | horizontal, vertical | horizontal |
+| `variant` | (omit for default), subtle | — |
+
+Note: in the class API the divider is an `<hr>` — in the custom-element form you can use
+`<sk-divider>` and the CSS handles display. Add `role="separator"`.
+
+**Example:**
+
+```html
+<sk-divider kind="neutral" role="separator"></sk-divider>
+```
+
+[See Vue docs →](/components/divider)
+
+---
+
+### sk-page
+
+**Tag:** `<sk-page>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `fixed-header` | Boolean presence | off |
+| `fixed-footer` | Boolean presence | off |
+| `flush` | Boolean presence | off |
+
+**Example:**
+
+```html
+<sk-page fixed-header>
+    <header class="sk-page-header">…</header>
+    <main class="sk-page-main">…</main>
+</sk-page>
+```
+
+[See Vue docs →](/components/page)
+
+---
+
+### sk-group
+
+**Tag:** `<sk-group>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `orientation` | horizontal, vertical | horizontal |
+
+**Example:**
+
+```html
+<sk-group>
+    <button class="sk-button sk-neutral" type="button">
+        <span class="sk-button-chrome">A</span>
+    </button>
+    <button class="sk-button sk-neutral" type="button">
+        <span class="sk-button-chrome">B</span>
+    </button>
+</sk-group>
+```
+
+[See Vue docs →](/components/group)
+
+---
+
+### sk-skeleton
+
+**Tag:** `<sk-skeleton>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `variant` | text, circular, rectangular, square | text |
+| `animation` | shimmer, pulse, none | shimmer |
+
+Note: width and height are set via inline `style` — there are no attribute equivalents.
+
+**Example:**
+
+```html
+<sk-skeleton variant="rectangular" animation="shimmer"
+             style="width: 200px; height: 40px;"></sk-skeleton>
+```
+
+[See Vue docs →](/components/skeleton)
+
+---
+
+### sk-progress
+
+**Tag:** `<sk-progress>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `kind` | neutral, primary, accent, info, success, warning, danger | neutral |
+| `size` | xs, sm, md, lg, xl | md |
+| `indeterminate` | Boolean presence | off |
+
+Also set the native `value` and `max` attributes.
+
+**Example:**
+
+```html
+<sk-progress kind="primary" size="sm" value="40" max="100"></sk-progress>
+```
+
+[See Vue docs →](/components/progress)
+
+---
+
+### sk-spinner
+
+**Tag:** `<sk-spinner>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `kind` | neutral, primary, accent, info, success, warning, danger | primary |
+| `size` | xs, sm, md, lg, xl | md |
+| `variant` | circular, dots, crosshair | circular |
+
+Note: the custom-element form does not inject the inner arc/dot DOM that the static helper
+and Vue component emit. Add `role="status"` and `aria-label="Loading"` manually.
+
+**Example:**
+
+```html
+<sk-spinner kind="accent" size="lg" variant="circular"
+            role="status" aria-label="Loading"></sk-spinner>
+```
+
+[See Vue docs →](/components/spinner)
+
+---
+
+### sk-navbar
+
+**Tag:** `<sk-navbar>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `kind` | neutral, primary, accent, info, success, warning, danger | neutral |
+| `sticky` | Boolean presence | on (sticky by default in class API) |
+
+Note: the `sk-sticky` class is applied by default via the static helper when `sticky !== false`.
+In the custom-element form, `sticky` is a boolean attribute — include it to enable, omit to disable.
+
+**Example:**
+
+```html
+<sk-navbar kind="neutral" sticky>
+    <div class="sk-navbar-content">
+        <div class="sk-navbar-brand">MySite</div>
+        <div class="sk-navbar-nav">…</div>
+    </div>
+</sk-navbar>
+```
+
+[See Vue docs →](/components/navbar)
+
+---
+
+### sk-toolbar
+
+**Tag:** `<sk-toolbar>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `kind` | neutral, primary, accent, info, success, warning, danger | neutral |
+| `orientation` | horizontal, vertical | horizontal |
+
+Add `role="toolbar"`.
+
+**Example:**
+
+```html
+<sk-toolbar kind="neutral" role="toolbar">
+    <button class="sk-button sk-neutral" type="button">
+        <span class="sk-button-chrome">Cut</span>
+    </button>
+    <button class="sk-button sk-neutral" type="button">
+        <span class="sk-button-chrome">Copy</span>
+    </button>
+</sk-toolbar>
+```
+
+[See Vue docs →](/components/toolbar)
+
+---
+
+### sk-sidebar
+
+**Tag:** `<sk-sidebar>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `kind` | neutral, primary, accent, info, success, warning, danger | neutral |
+| `side` | left, right | left |
+| `dense` | Boolean presence | off |
+
+Drawer open/close is Vue-only. The custom-element form is always visible.
+
+**Example:**
+
+```html
+<sk-sidebar kind="neutral">
+    <nav>…</nav>
+</sk-sidebar>
+```
+
+[See Vue docs →](/components/sidebar)
+
+---
+
+### sk-breadcrumbs
+
+**Tag:** `<sk-breadcrumbs>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `kind` | neutral, primary, accent, info, success, warning, danger | neutral |
+
+Add `aria-label="Breadcrumbs"`.
+
+**Example:**
+
+```html
+<sk-breadcrumbs kind="neutral" aria-label="Breadcrumbs">
+    <ol>
+        <li><a href="/">Home</a></li>
+        <li aria-current="page">Docs</li>
+    </ol>
+</sk-breadcrumbs>
+```
+
+[See Vue docs →](/components/breadcrumbs)
+
+---
+
+### sk-pagination
+
+**Tag:** `<sk-pagination>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `kind` | neutral, primary, accent, info, success, warning, danger | neutral |
+
+Add `aria-label="Pagination"`.
+
+**Example:**
+
+```html
+<sk-pagination kind="neutral" aria-label="Pagination">
+    <button class="sk-button sk-neutral" type="button">
+        <span class="sk-button-chrome">‹</span>
+    </button>
+    <button class="sk-button sk-primary" type="button" aria-current="page">
+        <span class="sk-button-chrome">1</span>
+    </button>
+    <button class="sk-button sk-neutral" type="button">
+        <span class="sk-button-chrome">›</span>
+    </button>
+</sk-pagination>
+```
+
+[See Vue docs →](/components/pagination)
+
+---
+
+### sk-tag
+
+**Tag:** `<sk-tag>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `kind` | neutral, primary, accent, info, success, warning, danger | neutral |
+| `size` | xs, sm, md, lg, xl | md |
+| `variant` | solid, outline, ghost | solid |
+| `removable` | Boolean presence | off |
+
+Note: content should be wrapped in `<span class="sk-tag-content">` for correct inner spacing.
+
+**Example:**
+
+```html
+<sk-tag kind="accent" size="sm" variant="outline">
+    <span class="sk-tag-content">Beta</span>
+</sk-tag>
+```
+
+[See Vue docs →](/components/tag)
+
+---
+
+### sk-avatar
+
+**Tag:** `<sk-avatar>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `kind` | neutral, primary, accent, info, success, warning, danger | neutral |
+| `size` | xs, sm, md, lg, xl | md |
+
+Note: there is no `shape` attribute — the Vue component does not expose a shape prop.
+Place the inner content (img, initials span, or fallback icon) as children.
+
+**Example:**
+
+```html
+<sk-avatar kind="primary" size="lg">
+    <img src="/avatar.jpg" alt="User" class="sk-avatar-image" />
+</sk-avatar>
+```
+
+[See Vue docs →](/components/avatar)
+
+---
+
+### sk-field
+
+**Tag:** `<sk-field>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `label-position` | top, left, right | top |
+| `has-error` | Boolean presence | off |
+
+**Example:**
+
+```html
+<sk-field label-position="top">
+    <label class="sk-field-label" for="email">Email</label>
+    <div class="sk-field-input-wrapper">
+        <input class="sk-input sk-neutral" id="email" type="email" />
+    </div>
+</sk-field>
+```
+
+[See Vue docs →](/components/field)
+
+---
+
+### sk-table
+
+**Tag:** `<sk-table>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `kind` | neutral, primary, accent, info, success, warning, danger | neutral |
+| `variant` | default, (others) | default |
+| `striped` | Boolean presence | off |
+| `hoverable` | Boolean presence | on by default (omit to disable via class: don't add `sk-hoverable`) |
+| `bordered` | Boolean presence | on by default |
+| `inner-borders` | Boolean presence | off (inner borders suppressed by default) |
+| `dark-background` | Boolean presence | off |
+| `subtle` | Boolean presence | off |
+
+Note: the custom-element form targets the `<table>` directly. The `sk-table-wrapper` div
+is a class-API / static-helper construct — it's not injected automatically for custom elements.
+
+**Example:**
+
+```html
+<sk-table kind="neutral" striped>
+    <thead><tr><th>Name</th><th>Role</th></tr></thead>
+    <tbody><tr><td>Alice</td><td>Engineer</td></tr></tbody>
+</sk-table>
+```
+
+[See Vue docs →](/components/table)
+
+---
+
+### sk-tooltip
+
+**Tag:** `<sk-tooltip>`
+
+**Attributes:**
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `kind` | neutral, primary, accent, info, success, warning, danger | neutral |
+| `variant` | solid, outline | solid |
+| `placement` | top, right, bottom, left | top |
+
+Add `role="tooltip"`. The Vue version includes trigger management and floating-UI positioning —
+the custom-element form is for static pre-positioned tooltip markup only.
+
+**Example:**
+
+```html
+<sk-tooltip kind="neutral" placement="top" role="tooltip">
+    Click to expand
+</sk-tooltip>
+```
+
+[See Vue docs →](/components/tooltip)
+
+---
+
+## Form controls: class-only {#form-controls}
+
+The following 12 components **do not** have a custom-element form and require the class API:
+Button, Input, Textarea, Select, Slider, ColorPicker, Checkbox, Radio, Switch, NumberInput,
+TagsInput, Dropdown.
+
+Use the [class API](./class-api.md) for all 12 of these components.

package/docs/guides/pure-css/index.md

@@ -0,0 +1,86 @@
+---
+title: Sleekspace Without Vue
+description: Use the Sleekspace design system in static sites and non-Vue apps via the class API, custom-element API, or static helper functions.
+---
+
+# Sleekspace Without Vue
+
+Sleekspace is a Vue 3 component library, but the design system itself is framework-agnostic.
+If you're building a static site — VitePress output, Astro, 11ty, a build-time script — you
+can use Sleekspace's visual language without shipping Vue or paying for hydration.
+
+## Quick lookup
+
+Common tasks and where to find them:
+
+| I want to… | Go here |
+|-----------|---------|
+| Build an alert box | [`alert()`](./static-helpers.md#alert) or [class form](./class-api.md#alert) |
+| Add a spinner | [`spinner()`](./static-helpers.md#spinner) or [class form](./class-api.md#spinner) |
+| Render a nav bar | [`navBar()`](./static-helpers.md#navbar) or [class form](./class-api.md#navbar) |
+| Lay out a page shell | [`page()`](./static-helpers.md#page) or [class form](./class-api.md#page) |
+| Show an avatar | [`avatar()`](./static-helpers.md#avatar) or [class form](./class-api.md#avatar) |
+| Wrap a form field | [`field()`](./static-helpers.md#field) or [class form](./class-api.md#field) |
+| Display a data table | [`table()`](./static-helpers.md#table) or [class form](./class-api.md#table) |
+| Add a tag / badge | [`tag()`](./static-helpers.md#tag) or [class form](./class-api.md#tag) |
+
+## Three ways to use Sleekspace without Vue
+
+### 1. Class API — Bootstrap-style HTML classes
+
+Ship the compiled CSS and write HTML directly.
+
+```html
+<link rel="stylesheet" href="/path/to/sleekspace-ui.css" />
+
+<div class="sk-panel sk-primary sk-lg">
+    <p>Primary panel, large cut size.</p>
+</div>
+```
+
+Works in any SSG, any language, any framework. Zero JS.
+
+[See the full class reference →](./class-api.md)
+
+### 2. Custom-element API — attribute-driven
+
+Author containers as light-DOM custom elements with attributes.
+
+```html
+<sk-panel kind="primary" size="lg">
+    <p>Same panel, attribute-driven.</p>
+</sk-panel>
+```
+
+Zero JS required — Sleekspace targets custom elements via attribute selectors, no registration
+needed. Form controls remain on native elements via the class API.
+
+[See the custom-element reference →](./custom-elements.md)
+
+### 3. Static helpers — Node SSG ergonomics
+
+Import typed helper functions from the `/static` subpath.
+
+```typescript
+import { panel, button } from '@skewedaspect/sleekspace-ui/static';
+
+const html = panel({ kind: 'primary', size: 'lg' }, `<p>Content</p>`);
+```
+
+Strongly typed, zero runtime dependencies, works in any Node-based SSG.
+
+[See the static helpers reference →](./static-helpers.md)
+
+## What you don't get
+
+The pure-CSS layer covers presentational components only. Interactive components that need JS
+state management (Modal, Toast, Accordion, Dropdown menu, TreeView, Tabs, etc.) remain Vue-only.
+
+[See the full limitations page →](./limitations.md)
+
+## Path chooser
+
+- **I just want to write HTML that looks like Sleekspace.** → [Class API](./class-api.md)
+- **I want attribute-driven ergonomics for containers.** → [Custom elements](./custom-elements.md)
+- **I'm building SSG output from Node.** → [Static helpers](./static-helpers.md)
+- **I want to know what's missing vs. the Vue version.** → [Limitations](./limitations.md)