@skewedaspect/sleekspace-ui 0.8.1 → 0.9.0

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

@@ -0,0 +1,152 @@
+---
+title: Pure-CSS Limitations
+description: What the pure-CSS layer of Sleekspace covers, what it doesn't, and when to reach for the Vue components instead.
+---
+
+# Pure-CSS Limitations
+
+Let's be direct: pure-CSS Sleekspace is not Sleekspace. It's the presentational subset — the
+parts that are just CSS talking to HTML structure. If you need interactivity, you need Vue.
+
+This page tells you exactly what that means so you can make the right call before you start.
+
+---
+
+## What's completely out of scope
+
+These components are Vue-only. There is no class-API, custom-element, or static-helper form
+for them, and there won't be — they fundamentally require JS state management.
+
+### Modal, Popover, ContextMenu, Toast
+
+All four require:
+- Portal/teleport rendering to a document-level container
+- Focus trapping and restoration
+- Escape-key and click-outside dismiss
+- ARIA attributes that change dynamically (`aria-expanded`, `aria-modal`)
+
+You cannot replicate a production-quality modal with CSS alone. Use the Vue components.
+
+### Tabs, Accordion, Collapsible, TreeView
+
+These are state machines:
+- Tabs track which panel is active, activate on click/keyboard, and update `aria-selected`
+- Accordion and Collapsible manage open/closed state and animate height
+- TreeView manages selection, expansion, keyboard navigation (arrow keys, Home/End)
+
+The `<details>` / CSS `:checked` tricks can approximate some of this for simple cases, but
+they break on complex trees, keyboard navigation, and multi-open scenarios. The Vue versions
+are correct; the CSS approximations are not.
+
+### Listbox, ScrollArea, Splitter
+
+- **Listbox** — needs selection state, keyboard navigation, and `aria-activedescendant`
+- **ScrollArea** — provides custom scrollbars via overflow regions; the pure-CSS scroll
+  styling applies to native scrollbars, not the JS-managed virtualized variant
+- **Splitter** — requires pointer capture and drag tracking to resize panes
+
+---
+
+## What's in scope but reduced
+
+These components exist in the pure-CSS layer but are missing capabilities present in the
+Vue versions.
+
+### Slider — single thumb only
+
+The static helper and class API render `<input type="range">`, which is inherently single-thumb.
+The Vue `SkSlider` supports dual-thumb range selection via two overlapping range inputs managed
+in JS. There is no CSS-only dual-thumb solution.
+
+**What you get:** A fully styled single-thumb slider with kind + size modifiers.
+**What's missing:** `min`/`max` value range selection (dual thumb).
+
+### Dropdown — `<details>` disclosure, not a menu
+
+The static helper renders `<details class="sk-dropdown"><summary>…</summary>…</details>`.
+This gives you a zero-JS disclosure widget that opens and closes. It is **not** a menu:
+- No focus trap
+- No arrow-key navigation between items
+- No `role="menu"` / `role="menuitem"` semantics
+- Items don't get `aria-checked` or keyboard activation
+
+Use this for simple show/hide disclosure patterns. For actual menus (accessible, keyboard-navigable
+dropdowns), use the Vue `SkDropdown`.
+
+### Select — popup styling is Chromium-only
+
+The class API applies `sk-select` to a native `<select>`. The closed button state (the
+select trigger) is fully cross-browser styled. However, the open popup panel (the dropdown
+list of options) only supports `appearance: base-select` styling in Chromium-based browsers
+(Chrome, Edge) as of 2026. Firefox and Safari show the native OS popup.
+
+If cross-browser custom select styling matters, use the Vue `SkSelect` which uses a custom
+floating-UI panel in all browsers.
+
+### ColorPicker — native swatch only
+
+The static helper renders `<input type="color">`. This gives you a styled color swatch button
+that opens the browser's native color picker on click. It respects the `size` modifier.
+
+**What's missing:**
+- The OKLCH palette panel
+- Hex / RGB / HSL / OKLCH format switching
+- The alpha channel slider
+- Any kind of themed appearance inside the popup (that's browser chrome)
+
+Use Vue `SkColorPicker` for the full-featured picker.
+
+### Alert, Spinner, NavBar, Sidebar, Tag, Avatar, Field, Table — inner DOM not auto-injected by custom elements
+
+The static helpers and Vue components for these 8 components emit an inner DOM structure beyond
+the root element (icon wrappers, content wrappers, inner panels, etc.). The custom-element
+form applies CSS via attribute selectors but does **not** inject this inner DOM — you must
+write it yourself when using `<sk-alert>`, `<sk-spinner>`, etc. as custom elements.
+
+Use the [static helpers](./static-helpers.md) or [class API examples](./class-api.md) to see
+the expected inner structure for each component.
+
+---
+
+## Browser caveats
+
+### `corner-shape: bevel`
+
+Sleekspace's beveled corners use `corner-shape: bevel` (CSS Shapes Level 2). This is supported
+in modern Chrome and emerging in other engines. Older browsers fall back to `clip-path: polygon(…)`
+which preserves the visual shape but loses the border rendering on cut edges. The fallback is
+provided automatically — no author action needed.
+
+### `color-mix(in oklch, …)`
+
+Theme colors are computed with `color-mix()` in the OKLCH color space for perceptually uniform
+mixing. This requires a modern browser (Chrome 111+, Firefox 113+, Safari 16.2+). Older browsers
+see the fallback static color values baked into the CSS custom properties.
+
+### `:where(:not(…))` chains
+
+Default modifier behavior (e.g., applying `sk-neutral` styles when no `kind` attribute is
+set) uses zero-specificity `:where()` with negation chains. This requires browsers that
+support `:where()` — all evergreen browsers since 2021. IE11 is not supported and never will be.
+
+---
+
+## When to reach for Vue instead
+
+Use the pure-CSS layer when:
+- You're building a static site (VitePress, Astro, 11ty) and want Sleekspace visuals without JS
+- You need the CSS for a non-JS environment (email templates, print stylesheets)
+- You're prototyping layout and just need the styling primitives
+- You want the look of Sleekspace in a non-Vue app (React, Svelte, plain HTML)
+
+Reach for the Vue components when:
+- You need any interactive component (Modal, Tabs, Accordion, etc.)
+- You need a production-quality Dropdown with keyboard navigation
+- You need dual-thumb Slider
+- You need cross-browser custom Select styling
+- You need the full ColorPicker palette UI
+- You need form validation integration (Vue components emit update events and expose validation state)
+- You need theme switching at runtime (Vue components react to the reactive theme store)
+
+The answer isn't always "use Vue." For purely presentational output — especially build-time
+HTML generation — the pure-CSS layer is lighter and perfectly correct.