Docs: Add New Examples Package (#195)

Author: jlukic

CHANGELOG.md

@@ -34,6 +34,7 @@ xx.xx.xxxx
 
 ### Query
 * **Bug** - Fixed `instanceof` checks failing for `Query.wrap()` instances — brand property was a class field (set only in constructor) but `wrap()` uses `Object.create()`. Moved to prototype getter so all prototype-chain objects pass the check regardless of construction path.
+* **Bug** - Fixed `.position({ type: 'global' })` placing elements with the wrong offset when a CSS containing block (transform/filter/perspective/etc.) lived outside the element's shadow DOM — `positioningParent` now pierces shadow boundaries so the math matches what the browser actually uses. `isInView` now does the same for its default clipping viewport.
 * **Feature** - Added `includeMargin`, `includePadding`, and `includeBorder` options to `naturalWidth()` and `naturalHeight()` — allows measuring unconstrained intrinsic dimensions while preserving the element's box model.
 
 ### Utils

ai/skills/authoring/example-curriculum.md

@@ -211,28 +211,29 @@ Proves SUI's reactivity works at animation speed — a `reaction()` drives `requ
 
 ---
 
-### 15. `event-data` — Dynamic Signal Access
+### 15. `solar-system-3d` — Wrapping a Graphics Pipeline
 
-Uses `data-*` attributes to dynamically select which signal and which mutation method to call. A single event handler handles all cases via bracket notation.
+A WebGL fragment shader rendering the solar system, with the component owning the canvas, the drag-to-orbit input, keyboard controls, and per-frame uniform uploads. Same reactivity-driven animation loop as the ball simulation, but extended into a full Processing.js-style imperative pipeline — keybindings, settings, and reactivity sit alongside the shader without fighting it. Sells SUI as a comfortable wrapper for graphics code.
 
-**New patterns:** `state[dimension][helper](settings.delta)` dynamic signal access, data-driven event dispatch.
+**New patterns:** Static `keys` with multi-character bindings (`'=, +'`), pointer-capture drag, sub-module imports (`fragment.js` / `vertex.js` / `webgl.js`), `state.frame.increment()` to tick the animation reaction, external preset orchestration via `$().settings({ visible: [...] })`.
 
 **What to notice:**
-- `state[dimension][helper](settings.delta)` — `dimension` and `helper` come from `data-dimension` and `data-helper` attributes on the button. One handler, many behaviors.
-- This pattern eliminates repetitive event handlers. Instead of separate handlers for each action, one handler reads data attributes to determine what to do.
+- Same `reaction()` + `requestAnimationFrame` shape as the ball simulation, but the tick is explicit: `state.frame.increment()` at the end of `render` advances the signal the reaction depends on.
+- Keybindings as first-class framework concerns. `'=, +'` and `'-, _'` bind both characters at once; `space` pauses; `o`/`s` toggle settings. Each handler mutates a setting that the next render reads as a shader uniform.
+- Shader source is a plain string exported from `fragment.js`. Sub-modules import into `component.js` the same way subtemplates do — the framework doesn't care that the strings happen to be GLSL.
+- `page.js` ships preset visibility arrays through a `ui-menu` and pipes the selection into the component: `$('solar-system-3d').settings({ visible: presets[value] })`. Settings are reactive, so the shader picks up the change on the next frame.
 
 ---
 
-### 16. `dropdown` — Real-World Form Component
+### 16. `event-data` — Dynamic Signal Access
 
-Form integration with hidden inputs, click-away dismissal, JSON arrays as HTML attributes.
+Uses `data-*` attributes to dynamically select which signal and which mutation method to call. A single event handler handles all cases via bracket notation.
 
-**New patterns:** Hidden `<input>` for forms, `onChange` callback alongside `dispatchEvent`, `el.contains(event.target)`, JSON in attributes, `{classIf}`.
+**New patterns:** `state[dimension][helper](settings.delta)` dynamic signal access, data-driven event dispatch.
 
 **What to notice:**
-- `options='[{"value": "apple", "text": "Apple"}]'` — JSON in HTML attributes, auto-parsed for array/object settings.
-- `settings.onChange` alongside `dispatchEvent` — supports both callbacks and DOM events.
-- `{classIf isOpen 'visible'}` — simpler than `classMap` for a single conditional class.
+- `state[dimension][helper](settings.delta)` — `dimension` and `helper` come from `data-dimension` and `data-helper` attributes on the button. One handler, many behaviors.
+- This pattern eliminates repetitive event handlers. Instead of separate handlers for each action, one handler reads data attributes to determine what to do.
 
 ---
 
@@ -296,7 +297,7 @@ SVG rendering and the `interval` helper with automatic lifecycle cleanup.
 | `'global event target'` | `context-menu` |
 | `'deep event selector'` | `context-menu` |
 | `{>slot}` content projection | `context-menu` |
-| `classMap` / `activeIf` / `selectedIf` / `classIf` | `emoji-reactions` / `todo-list` / `dropdown` |
+| `classMap` / `activeIf` / `selectedIf` / `classIf` | `emoji-reactions` / `todo-list` |
 | `reaction()` for side effects | `todo-list` |
 | `peek()` for non-reactive reads | `context-menu` |
 | `dispatchEvent` (→ `event.detail`) | `context-menu` |
@@ -320,8 +321,8 @@ SVG rendering and the `interval` helper with automatic lifecycle cleanup.
 | Lisp-style expressions | `async-search` |
 | JS-style expressions | `card-search` |
 | `afterFlush` | `todo-list` |
-| JSON in HTML attributes | `dropdown` |
-| Form integration (hidden input) | `dropdown` |
+| Sub-module imports (shader / data files) | `solar-system-3d` |
+| WebGL inside shadow DOM | `solar-system-3d` |
 | `{#each ... else}` | `card-search` |
 | `range()` helper | `rating-slider` |
 | `{both x y}` compound conditional | `progress-bar` |

docs/src/components/SpecimenExplorer/SpecimenExplorer.html

@@ -30,7 +30,7 @@
     <ui-panel size="280px" min-size="200px" max-size="400px">
       <ui-panels direction="vertical" class="control-panels">
         {#each group in getControlGroups}
-          <ui-panel size="{#if group.last}grow{else}natural{/if}" label="{group.label}">
+          <ui-panel size="{#if true}grow{/if}" label="{group.label}">
             <div class="section-controls">
               {#each control in group.controls}
                 {#if is control.type 'radio'}

docs/src/examples/component/advanced-ball-simulation/component.js

@@ -262,7 +262,7 @@ const createComponent = ({ self, $, reaction, settings, state }) => ({
   },
   getPointerPosition(event) {
     const canvas = self.getCanvas();
-    const rect = canvas.getBoundingClientRect();
+    const rect = $('canvas').bounds();
     const scaleX = canvas.width / rect.width;
     const scaleY = canvas.height / rect.height;
     return {
@@ -272,7 +272,7 @@ const createComponent = ({ self, $, reaction, settings, state }) => ({
   },
 });
 
-const onRendered = ({ state, data, settings, self }) => {
+const onRendered = ({ self }) => {
   self.drawInitialBalls();
   self.startAnimation();
 };

docs/src/examples/component/async-search/component.css

@@ -5,7 +5,12 @@
   display: block;
 
   .results {
-    margin-top: 5px;
+    position: absolute;
+    top: 100%;
+    left: 0;
+    right: 0;
+    z-index: var(--float-layer);
+    margin-top: var(--margin-3xs);
     box-shadow: var(--floating-shadow);
     border: var(--strong-border);
     background-color: var(--inverted-100);

docs/src/examples/component/async-search/component.js

@@ -73,7 +73,6 @@ const createComponent = ({ $, state, settings, self, timeout }) => ({
   selectCurrent() {
     const index = state.selectedIndex.get();
     const result = self.results[index];
-    console.log(index, result);
     if (result) {
       self.clearSearch();
       self.setValue(result);

docs/src/examples/component/card-search/card.js

@@ -4,7 +4,6 @@ const css = await getText('./card.css');
 const template = await getText('./card.html');
 
 export const card = defineComponent({
-  renderingEngine: 'native',
   template,
   css,
 });

docs/src/examples/component/card-search/component.html

@@ -11,7 +11,6 @@
         role=friend.role
         joined=friend.joined
         image=friend.image
-        contacts=friend.contacts
       }
     {else}
       No {filter != 'all' ? filter : ''} results for "{searchTerm}"

docs/src/examples/component/card-search/component.js

@@ -1,5 +1,5 @@
 import { defineComponent, getText } from '@semantic-ui/component';
-import { each, escapeRegExp, get, weightedObjectSearch } from '@semantic-ui/utils';
+import { weightedObjectSearch } from '@semantic-ui/utils';
 
 // sub templates
 import { card } from './card.js';
@@ -48,15 +48,14 @@ const events = {
   'change ui-menu'({ state, data }) {
     state.filter.set(data.value);
   },
-  'input ui-input'({ state, value, target }) {
+  'input ui-input'({ state, value }) {
     state.searchTerm.set(value);
   },
 };
 
 defineComponent({
   tagName: 'friend-directory',
   template,
-  renderingEngine: 'native',
   css,
   defaultState,
   events,

docs/src/examples/component/context-menu/component.html

@@ -1,26 +1,26 @@
 <div class="trigger">
   {>slot}
 </div>
-<div class="{classMap getMenuStates} menu" style="{getMenuStyle}" role="menu" part="menu">
+<div class="{classIf visible 'visible'} menu" style="width: {width}px;" role="menu" part="menu">
   <div class="items">
-    {#each item in items}
-      {#if isDivider item}
-        <div class="divider" data-divider="true"></div>
+    {#each item, index in items}
+      {#if item.divider}
+        <div class="divider"></div>
       {else}
-        <div 
-          class="item {classMap getItemStates index}"
+        <div
+          class="item {activeIf (activeIndex == index)}"
           data-index="{index}"
           role="menuitem"
           part="menu-item"
-          tabindex="{(isItemActive(index) ? '0' : '-1')}"
+          tabindex="{activeIndex == index ? '0' : '-1'}"
         >
-          {#if hasIcon item}
+          {#if item.icon}
             <span class="icon" part="icon">
               <ui-icon icon="{item.icon}"></ui-icon>
             </span>
           {/if}
           <span class="label" part="label">{item.label}</span>
-          {#if hasShortcut item}
+          {#if item.shortcut}
             <span class="shortcut" part="shortcut">{item.shortcut}</span>
           {/if}
         </div>