@kenlo/sds-design-system 0.9.9

package/components/Floating/floating.marko

@@ -0,0 +1,291 @@
+<!-- sds-floating — ported from kdls-design-system v2.5.1 (0f3edf8) components/Floating/Floating.tsx.
+
+     A trigger and a panel that finds its own place: twelve placements, a flip when there
+     is no room, and four ways to open it. Popover, Tooltip, DatePicker and ColorPicker are
+     all this component with a different panel inside.
+
+     It hydrates, and that is not a concession — there is nothing here but interaction. The
+     panel is not rendered at all until it opens, so a page full of closed popovers ships
+     the triggers and a few bytes of state each, not the panels.
+
+     Divergences, and both come from the same place:
+
+     KDLS renders the panel through ReactDOM.createPortal into <body>. Marko 5 has no
+     portal, and the obvious substitute does not work: measured in the portal on
+     2026-09-10, a node moved to <body> with appendChild goes back to where the template
+     says it belongs on the component's next re-render — and a floating panel re-renders
+     every time it opens. So the panel stays in the tree and is positioned with
+     `position: fixed`, which escapes `overflow: hidden` on its own.
+
+     What fixed does not escape is an ancestor with a transform, a filter, a perspective or
+     `contain: paint` — any of those becomes the containing block for fixed descendants, and
+     the panel is then positioned, and clipped, against that ancestor instead of the
+     viewport. That is a silent visual bug, so the component looks for one when it opens and
+     says so in the console rather than drawing the panel somewhere wrong with no
+     explanation. See findFixedContainingBlock in floating-position.js.
+
+     Four of KDLS's attributes are not here, and each for a reason rather than an oversight:
+
+       destroyOnClose      always true. The panel is not rendered at all while closed, so
+                           there is nothing to destroy and nothing to keep — a page of
+                           closed popovers ships its triggers and a few bytes of state.
+       getPopupContainer   names the element a portal renders into, and there is no portal.
+       openClassName       is `openClass` here, because Marko has no className anywhere.
+       triggerClassName    KDLS wraps the caller's trigger in a div to hang a class on. The
+                           trigger is the body here and nothing wraps it; a caller who wants
+                           a class puts it on their own element, which is one fewer element
+                           in everyone's DOM.
+
+     The panel is measured before it is shown. A panel that has not been measured is 0x0,
+     0x0 fits anywhere, and a flip decided on that basis puts the panel on the wrong side
+     in front of the visitor. So it renders hidden, gets measured, and is revealed in one
+     step — `positioned` is that step. -->
+
+import {
+  parseFloatingPlacement, joinFloatingPlacement, camelToKebab, computeFloatingPosition,
+  getVisibleBounds, findFixedContainingBlock, assertPlacement, assertTrigger, DEFAULT_GAP,
+} from "./floating-position.js";
+
+class {
+  onCreate(input) {
+    this.state = {
+      open: !!input.defaultOpen,
+      positioned: false,
+      style: null,
+      side: parseFloatingPlacement(input.placement || "top").side,
+    };
+    this.openTimer = null;
+    this.closeTimer = null;
+  }
+
+  get isOpen() {
+    return this.input.open !== undefined ? this.input.open : this.state.open;
+  }
+
+  get modes() {
+    return [].concat(this.input.trigger || "click");
+  }
+
+  setOpen(next) {
+    if (next === this.isOpen) return;
+    if (this.input.open === undefined) this.state.open = next;
+    this.input.onOpenChange?.(next);
+    if (!next) this.state.positioned = false;
+  }
+
+  onMount() {
+    this.reposition = () => this.position();
+    // `true` for the capture phase: a panel anchored to something inside a scrolling list
+    // has to follow it, and a scroll event on that list does not bubble to window.
+    window.addEventListener("scroll", this.reposition, true);
+    window.addEventListener("resize", this.reposition);
+
+    // Closing on a pointer outside is what makes a floating panel feel like one. It is on
+    // the document because the press that should close it happens outside this tree, and
+    // on mousedown rather than click so a drag that starts outside closes it too.
+    this.onDocumentPointer = (event) => this.handleDocumentPointer(event);
+    document.addEventListener("mousedown", this.onDocumentPointer);
+
+    if (this.isOpen) this.afterOpen();
+  }
+
+  onUpdate() {
+    if (this.isOpen && !this.state.positioned) this.afterOpen();
+  }
+
+  onDestroy() {
+    window.removeEventListener("scroll", this.reposition, true);
+    window.removeEventListener("resize", this.reposition);
+    document.removeEventListener("mousedown", this.onDocumentPointer);
+    clearTimeout(this.openTimer);
+    clearTimeout(this.closeTimer);
+  }
+
+  afterOpen() {
+    // One frame, so the panel exists and has a size to measure. Position, then reveal.
+    requestAnimationFrame(() => {
+      if (!this.isOpen) return;
+      this.position();
+      this.state.positioned = true;
+      this.warnAboutContainingBlock();
+    });
+  }
+
+  position() {
+    const trigger = this.getEl("root");
+    const panel = this.getEl("panel");
+    if (!trigger || !panel) return;
+
+    const { side, align } = parseFloatingPlacement(this.input.placement || "top");
+    const gap = this.input.gap ?? DEFAULT_GAP;
+    const result = computeFloatingPosition(
+      trigger.getBoundingClientRect(),
+      { width: panel.offsetWidth, height: panel.offsetHeight },
+      side,
+      align,
+      gap,
+      getVisibleBounds(trigger, true),
+    );
+
+    this.state.side = result.effectiveSide;
+    this.state.style = this.input.matchTriggerWidth
+      ? { ...result.style, minWidth: trigger.getBoundingClientRect().width }
+      : result.style;
+  }
+
+  /** Said once per component, and only when there is something to say. */
+  warnAboutContainingBlock() {
+    if (this.warned) return;
+    const breaker = findFixedContainingBlock(this.getEl("root"));
+    if (!breaker) return;
+    this.warned = true;
+    console.error(
+      "[sds-floating] An ancestor with a transform, filter, perspective or contain:paint " +
+      "is the containing block for this panel, so it is positioned against that element " +
+      "instead of the viewport and may be clipped by it.",
+      breaker,
+    );
+  }
+
+  /**
+   * The click handler sits on the root because the trigger is whatever the caller put in
+   * the body — there is no element of ours to hang it on. But the panel is in that same
+   * root, so a click on anything inside it bubbles up here, and toggling on that would
+   * close the panel the moment the visitor used it: every option in a Select, every button
+   * in a Popover.
+   */
+  toggle(event) {
+    if (event && this.getEl("panel")?.contains(event.target)) return;
+    this.setOpen(!this.isOpen);
+  }
+
+  handleTriggerKey(event) {
+    if (this.getEl("panel")?.contains(event.target)) {
+      // Escape still closes from inside; Enter and Space belong to whatever has focus.
+      if (event.key === "Escape") this.setOpen(false);
+      return;
+    }
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      this.toggle();
+      return;
+    }
+    if (event.key === "Escape") this.setOpen(false);
+  }
+
+  handleContextMenu(event) {
+    event.preventDefault();
+    this.setOpen(true);
+  }
+
+  enter() {
+    clearTimeout(this.closeTimer);
+    this.openTimer = setTimeout(() => this.setOpen(true), this.input.mouseEnterDelay ?? 100);
+  }
+
+  leave() {
+    clearTimeout(this.openTimer);
+    this.closeTimer = setTimeout(() => this.setOpen(false), this.input.mouseLeaveDelay ?? 100);
+  }
+
+  /** Crossing the gap between trigger and panel must not close it. */
+  panelEnter() {
+    if (this.modes.includes("hover")) clearTimeout(this.closeTimer);
+  }
+
+  panelLeave(event) {
+    if (!this.modes.includes("hover")) return;
+    // Moving from the panel back onto the trigger is not leaving. The panel is a child of
+    // the root, so the root's `mouseenter` does not fire again — the pointer never left it
+    // — and nothing cancelled the close this scheduled. So a hover panel closed under a
+    // pointer that was sitting on the very thing that opens it, and reading a tooltip by
+    // moving back over its trigger was impossible.
+    const root = this.getEl("root");
+    if (root && event?.relatedTarget instanceof Node && root.contains(event.relatedTarget)) {
+      return;
+    }
+    this.leave();
+  }
+
+  handleFocus() { this.setOpen(true); }
+
+  handleBlur(event) {
+    if (this.getEl("panel")?.contains(event.relatedTarget)) return;
+    this.setOpen(false);
+  }
+
+  handleDocumentPointer(event) {
+    if (!this.isOpen) return;
+    const root = this.getEl("root");
+    const panel = this.getEl("panel");
+    if (root?.contains(event.target) || panel?.contains(event.target)) return;
+    this.setOpen(false);
+  }
+}
+
+$ {
+  const {
+    placement = "top",
+    trigger = "click",
+    zIndex,
+    class: extraClass = "",
+    openClass = "",
+  } = input;
+
+  assertPlacement(placement);
+  assertTrigger(trigger);
+
+  const { align } = parseFloatingPlacement(placement);
+  const open = component.isOpen;
+  const modes = [].concat(trigger);
+  const activePlacement = joinFloatingPlacement(state.side, align);
+
+  const rootClass = [
+    "sds-floating",
+    extraClass,
+    open ? openClass : "",
+  ].filter(Boolean).join(" ");
+
+  const panelClass = [
+    "sds-floating__panel",
+    `sds-floating__panel--${camelToKebab(activePlacement)}`,
+    state.positioned ? "sds-floating__panel--positioned" : "",
+  ].filter(Boolean).join(" ");
+
+  const px = (n) => (typeof n === "number" ? `${n}px` : n);
+  const panelStyle = [
+    "position:fixed",
+    state.style ? `top:${px(state.style.top)}` : "",
+    state.style ? `left:${px(state.style.left)}` : "",
+    state.style?.transform ? `transform:${state.style.transform}` : "",
+    state.style?.minWidth ? `min-width:${px(state.style.minWidth)}` : "",
+    zIndex !== undefined ? `z-index:${zIndex}` : "",
+  ].filter(Boolean).join(";");
+}
+
+<div
+  key="root"
+  class=rootClass
+  on-click(modes.includes("click") ? "toggle" : null)
+  on-keydown(modes.includes("click") ? "handleTriggerKey" : null)
+  on-mouseenter(modes.includes("hover") ? "enter" : null)
+  on-mouseleave(modes.includes("hover") ? "leave" : null)
+  on-focusin(modes.includes("focus") ? "handleFocus" : null)
+  on-focusout(modes.includes("focus") ? "handleBlur" : null)
+  on-contextmenu(modes.includes("contextMenu") ? "handleContextMenu" : null)
+>
+  <${input.renderBody}/>
+
+  <if(open)>
+    <div
+      key="panel"
+      class=panelClass
+      style=panelStyle
+      data-placement=activePlacement
+      on-mouseenter("panelEnter")
+      on-mouseleave("panelLeave")
+    >
+      <${input.content}/>
+    </div>
+  </if>
+</div>

package/components/Form/Form.css

@@ -0,0 +1,15 @@
+/* SDS Form.
+   KDLS has no Form.css at all: its Form is a context provider around a bare <form>, and a
+   <form> has no styling of its own to speak of.
+
+   This file exists because the form is now also the thing that tells its fields when to
+   validate, and that needs a class to hang on — and because every component in this system
+   ships a stylesheet, which is a rule with a test behind it. The rules below are the two a
+   bare <form> actually needs: no margin from the user agent, and a layout that stacks. */
+
+.sds-form {
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-4);
+}

package/components/Form/form-context.js

@@ -0,0 +1,69 @@
+/**
+ * What a form tells the fields inside it, without React context.
+ *
+ * KDLS's Form is a context provider: it holds `validateOn` and `submitted`, and every Input
+ * reads them with useFormContext. Marko 5 has no context and no equivalent — see
+ * .claude/component-rules.md §2c, where the same gap was settled once for compound
+ * components by using attribute tags. That answer does not work here: a form's children are
+ * arbitrary markup at any depth, not a list of known slots.
+ *
+ * So the form says it on the element itself, and a field asks the nearest form when it
+ * mounts. That is what context does — a child looking up the tree — expressed in the one
+ * tree both of them already share.
+ *
+ * Three consequences worth stating rather than discovering:
+ *
+ *   1. The lookup happens on mount, not during render, so the server cannot know it. That
+ *      costs nothing: validation is a client-side behaviour, and a field that has never
+ *      been touched has nothing to say anyway.
+ *
+ *   2. A field can still be told directly. An explicit `validateOn` wins over the form's,
+ *      which is KDLS's rule too (validateOnProp ?? contextValidateOn).
+ *
+ *   3. It works through any nesting, including a field inside a component inside a fieldset
+ *      inside the form — closest() does not care how deep it is.
+ */
+
+export const VALIDATE_ON = ['change', 'blur', 'submit'];
+
+export const DEFAULT_VALIDATE_ON = 'change';
+
+/** The attribute the form writes and the fields read. */
+export const VALIDATE_ON_ATTRIBUTE = 'data-sds-validate-on';
+
+/** The event a form fires at its fields when it is submitted. */
+export const SUBMIT_EVENT = 'sds-form-submit';
+
+export function assertValidateOn(value) {
+  if (!VALIDATE_ON.includes(value)) {
+    throw new Error(`Unknown validateOn: "${value}". Allowed: ${VALIDATE_ON.join(', ')}`);
+  }
+  return value;
+}
+
+/**
+ * When the form around `element` wants its fields validated.
+ *
+ * Returns null when there is no form, or the form said nothing — a field on its own page is
+ * not inside a form, and should keep its own behaviour rather than inherit a default it was
+ * never given.
+ */
+export function validateOnFor(element) {
+  const form = element?.closest?.(`form[${VALIDATE_ON_ATTRIBUTE}]`);
+  if (!form) return null;
+  const value = form.getAttribute(VALIDATE_ON_ATTRIBUTE);
+  return VALIDATE_ON.includes(value) ? value : null;
+}
+
+/**
+ * Tells every field inside `form` that it was submitted.
+ *
+ * A bubbling event rather than a property, so a field added after the form rendered still
+ * hears it, and so nothing has to keep a list of who is listening.
+ */
+export function announceSubmit(form) {
+  form?.dispatchEvent(new CustomEvent(SUBMIT_EVENT, { bubbles: false }));
+  for (const field of form?.querySelectorAll('[data-sds-field]') ?? []) {
+    field.dispatchEvent(new CustomEvent(SUBMIT_EVENT, { bubbles: false }));
+  }
+}

package/components/Form/form.marko

@@ -0,0 +1,73 @@
+<!-- sds-form — ported from kdls-design-system v2.5.1 (0f3edf8) components/Form/Form.tsx.
+
+     A <form> that tells the fields inside it when to validate, and tells them when it has
+     been submitted.
+
+     KDLS does that with a React context provider. Marko 5 has no context and no equivalent
+     — the gap was settled once for compound components by using attribute tags
+     (.claude/component-rules.md §2c), and that answer does not fit here: a form's children
+     are arbitrary markup at any depth, not a list of known slots.
+
+     So the form writes what it wants on its own element and fires an event at its fields
+     when it is submitted; a field asks the nearest form when it mounts and listens for that
+     event. That is what context is — a child looking up the tree — said in the one tree both
+     of them already share. The reasoning and its three consequences are in form-context.js.
+
+     This is the open question from Phase 1, answered rather than deferred. It is reversible:
+     nothing else depends on the mechanism, and if Marko ever grows a context the components
+     change in one place each. -->
+
+import {
+  assertValidateOn, announceSubmit, VALIDATE_ON_ATTRIBUTE, DEFAULT_VALIDATE_ON,
+} from "./form-context.js";
+import { rehyphenate } from "../../foundations/attrs.js";
+
+class {
+  handleSubmit(event) {
+    // The fields are told before the caller is, so a handler that reads the form's validity
+    // sees the result of this submission rather than the last one.
+    announceSubmit(this.getEl("form"));
+    this.input.onSubmit?.(event);
+  }
+}
+
+$ {
+  const {
+    validateOn = DEFAULT_VALIDATE_ON,
+    noValidate = true,
+    class: extraClass = "",
+  } = input;
+
+  assertValidateOn(validateOn);
+
+  // Everything else the caller wrote, forwarded.
+  //
+  // The form used to list six attributes and drop the rest in silence: `aria-labelledby`,
+  // `aria-describedby`, `role`, `target`, `enctype`, `autocomplete`, every `data-*`. A
+  // form named by a heading elsewhere on the page simply had no name, and nothing said so.
+  // KDLS spreads its rest props, which is the behaviour a caller expects from a component
+  // wrapping one native element.
+  //
+  // The four this component owns are held back: `class` is composed with the base class,
+  // and `validateOn`, `noValidate` and `onSubmit` are its own contract rather than the
+  // <form>'s. `renderBody` is Marko's.
+  const OWN = new Set(["validateOn", "noValidate", "class", "onSubmit", "renderBody"]);
+  const forwarded = rehyphenate(Object.fromEntries(
+    Object.entries(input).filter(([key]) => !OWN.has(key)),
+  ));
+}
+
+<!-- noValidate by default: the browser's own bubbles cannot be styled, cannot be themed,
+     and say things in the browser's language rather than the product's. The fields do the
+     validating and say it in the page. A caller who wants the native behaviour back passes
+     noValidate=false. -->
+<form
+  key="form"
+  ...forwarded
+  class=`sds-form ${extraClass}`.trim()
+  novalidate=(noValidate || null)
+  ...{ [VALIDATE_ON_ATTRIBUTE]: validateOn }
+  on-submit("handleSubmit")
+>
+  <${input.renderBody}/>
+</form>

package/components/GradientPicker/GradientPicker.css

@@ -0,0 +1,179 @@
+/* SDS GradientPicker.
+   Designed for SDS — KDLS has no counterpart, because its one gradient was a fixed brand
+   value rather than something a site chooses. Built to the design at
+   figma.com/design/HefwQxdw5h6wrhjzC9FHtf?node-id=11362-100508; every measurement below
+   is that frame's, expressed in tokens where a token holds the same number.
+   ============================================================ */
+
+.sds-gradient-picker {
+  display: inline-block;
+}
+
+.sds-gradient-picker--fill {
+  display: block;
+  width: 100%;
+}
+
+/* ── Trigger ──
+   The ColorPicker's shape, so the two read as the same kind of control in a row. */
+.sds-gradient-picker__trigger {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-3);
+  height: 56px;
+  padding: 0 var(--spacing-3);
+  background: var(--component-bg-color);
+  border: 1px solid var(--border-interactive-color);
+  border-radius: var(--radius-md);
+  cursor: pointer;
+  font-family: var(--font-family-base);
+  transition: border-color 120ms ease;
+  box-sizing: border-box;
+  outline: none;
+}
+
+.sds-gradient-picker__trigger:hover:not(:disabled),
+.sds-gradient-picker__trigger:focus-visible {
+  border-color: var(--color-primary-50-solid);
+}
+
+.sds-gradient-picker__trigger:focus-visible {
+  box-shadow: var(--focus-ring);
+}
+
+.sds-gradient-picker__trigger:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.sds-gradient-picker__swatch {
+  width: 24px;
+  height: 24px;
+  border-radius: var(--radius-sm);
+  flex-shrink: 0;
+  border: 1px solid var(--border-interactive-color);
+}
+
+.sds-gradient-picker__field {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  text-align: left;
+}
+
+/* ── Panel ──
+   460 × 420 with a 16px inset, and 16px between every part of it. */
+.sds-gradient-picker__panel {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-4);
+  width: 460px;
+  max-width: 100%;
+  padding: var(--spacing-4);
+  background: var(--component-bg-color);
+  border: 1px solid var(--border-static-color);
+  border-radius: var(--radius-md);
+  box-sizing: border-box;
+}
+
+.sds-gradient-picker__stops {
+  display: flex;
+  align-items: stretch;
+  gap: var(--spacing-4);
+}
+
+.sds-gradient-picker__stop {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-4);
+  flex: 1;
+  min-width: 0;
+}
+
+.sds-gradient-picker__divider {
+  width: 1px;
+  background: var(--border-static-color);
+  flex-shrink: 0;
+}
+
+/* ── Rails ──
+   A 20px track inside a 24px row, so the thumb overhangs by 2px top and bottom exactly as
+   it does in the design. The row is what takes the pointer, so the 4px of overhang stays
+   grabbable. */
+.sds-gradient-picker__rail {
+  position: relative;
+  height: 24px;
+  border-radius: var(--radius-full);
+  cursor: pointer;
+  outline: none;
+  background-clip: content-box;
+  padding: 2px 0;
+  box-sizing: border-box;
+}
+
+/* The hue wheel, written as hue angles rather than as picked colours — the ColorPicker's
+   rail says it the same way. These are not palette values and could not come from tokens:
+   they are the axis this control moves along. */
+.sds-gradient-picker__rail--hue {
+  background-image: linear-gradient(to right,
+    hsl(0, 100%, 50%), hsl(30, 100%, 50%), hsl(60, 100%, 50%),
+    hsl(120, 100%, 50%), hsl(180, 100%, 50%), hsl(240, 100%, 50%),
+    hsl(300, 100%, 50%), hsl(360, 100%, 50%)
+  );
+}
+
+.sds-gradient-picker__rail:focus-visible {
+  box-shadow: var(--focus-ring);
+}
+
+.sds-gradient-picker__thumb {
+  position: absolute;
+  top: 50%;
+  width: 24px;
+  height: 24px;
+  margin-left: -12px;
+  transform: translateY(-50%);
+  border-radius: var(--radius-full);
+  background: var(--component-bg-color);
+  box-shadow: 0 1px 4px var(--color-opacity-20);
+  pointer-events: none;
+}
+
+/* ── Preview ──
+   40px. The Figma frame draws it at 164, and Rafael's call is 40: a band is enough to read
+   where the two hues meet, and 164 makes the panel taller than most places that open it.
+   Noted rather than silently diverged. */
+.sds-gradient-picker__preview {
+  height: 40px;
+  border-radius: var(--radius-sm);
+}
+
+/* ── Overlay ──
+   The panel centred over the page rather than anchored to its trigger. Used where
+   anchoring cannot work: inside another panel, where it would land on top of the panel it
+   came from, and on a phone, where there is no room beside a trigger. */
+.sds-gradient-picker__backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: var(--z-overlay);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--spacing-4);
+  /* The scrim the Modal uses, and its dark-theme twin: --color-opacity-* inverts, so a
+     backdrop written with it goes white on a dark page. */
+  background: var(--color-opacity-50);
+  overflow-y: auto;
+}
+
+[data-theme="dark"] .sds-gradient-picker__backdrop {
+  background: var(--color-scrim);
+}
+
+/* Driven entirely from outside, with no trigger of its own: the root still has to be in
+   the tree — it is what holds the overlay — but it must not take up a line while the
+   overlay is closed. `display: contents` leaves the element addressable and gives its box
+   away. */
+.sds-gradient-picker--headless {
+  display: contents;
+}