@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/tilt.gts

@@ -0,0 +1,194 @@
+// Pretui — Tilt: a surface that tilts in 3D toward the pointer.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+// Caller-supplied hues are strings and must clear the kit-wide allowlist
+// before they reach an inline style — see pretui-css.gts.
+import { cssNumber } from '../pretui-css';
+import { pointerField } from '../internal/motion-pointer';
+
+// ── Tilt ─────────────────────────────────────────────────────────────────
+// TRANSCRIBED from motion-primitives tilt.tsx.
+//
+// Upstream engine: two springs feed useTransform ramps into a
+// `perspective(1000px) rotateX() rotateY()` motion template, retargeted
+// from React's onMouseMove. rotationFactor defaults to 15°, which reads as
+// a toy. There is no resting treatment at all — the wrapper is a bare
+// motion.div — no touch behavior, no keyboard behavior, and nothing in a
+// still frame.
+//
+// HONEST ASSESSMENT, stated where a reader will find it: an idle tilt
+// ENCODES NOTHING. Law 8 names it as the canonical cut. It ships because
+// five kits converged on it, and it earns its place on two grounds, both
+// of which are real in a still frame:
+//   (a) @plate — the tilted thing is an actual Pretui surface (card
+//       radius, --pretui-shadow-card at rest lifting to
+//       --pretui-shadow-raised on engage). The screenshot shows an
+//       elevated card, which is a component; the tilt is a garnish on it.
+//   (b) @press — the plate tips toward the ACTUAL press point and sinks
+//       slightly. That does encode a state transition: pressed, and here.
+//       If you keep only one behavior of this component, keep that one.
+// Everything else about it is decoration and is labelled so in the demo.
+//
+// This version: rotation is a `transform` calc over --pretui-nx/ny with a
+// CSS transition. Differences from the spring: no overshoot on return.
+// Default @max is 8°, not 15°. Dropped: `springOptions`, and `style`
+// pass-through (…attributes covers it). Touch: coarse pointers get no
+// rotation — a tilt under a fingertip is invisible and reads as drift —
+// but keep the press response. Keyboard: focusin flattens the plate to
+// neutral so a focused control is never read at an angle. Reduced motion:
+// rotation is removed entirely (this is the most vestibular of the four),
+// leaving the flat resting plate as the end state.
+export interface TiltSignature {
+  Args: {
+    /** maximum rotation in degrees at the corners — default 8 (upstream's
+     * 15 reads as a toy) */
+    max?: number;
+    /** invert the rotation, so the surface leans away from the pointer */
+    reverse?: boolean;
+    /** perspective depth in px — larger is flatter. Default 900 */
+    perspective?: number;
+    /** the moving specular sheen — default true */
+    glare?: boolean;
+    /** give the tilted thing a real Pretui card surface (radius +
+     * elevation). Default true; this is the resting state that makes the
+     * component visible in a still frame */
+    plate?: boolean;
+    /** tip toward and sink at the press point on pointerdown — default
+     * true. This is the only part of Tilt that encodes anything */
+    press?: boolean;
+  };
+  Blocks: {
+    /** the tilted content */
+    default: [];
+  };
+  Element: HTMLDivElement;
+}
+
+export class Tilt extends Component<TiltSignature> {
+  get showGlare(): boolean {
+    return this.args.glare ?? true;
+  }
+  get plate(): string {
+    return (this.args.plate ?? true) ? 'true' : 'false';
+  }
+  get press(): string {
+    return (this.args.press ?? true) ? 'true' : 'false';
+  }
+  get rootStyle(): ReturnType<typeof htmlSafe> {
+    let bits = [`--pretui-tilt-sign: ${this.args.reverse ? -1 : 1}`];
+    {
+      let n = cssNumber(this.args.max, -360, 360);
+      if (n !== undefined) {
+        bits.push(`--pretui-tilt-max: ${n}`);
+      }
+    }
+    {
+      let n = cssNumber(this.args.perspective, 0, 100000);
+      if (n !== undefined) {
+        bits.push(`--pretui-tilt-perspective: ${n}px`);
+      }
+    }
+    return htmlSafe(bits.join('; '));
+  }
+  <template>
+    <div
+      class='pretui-tilt'
+      style={{this.rootStyle}}
+      data-plate={{this.plate}}
+      data-press={{this.press}}
+      data-test-pretui-tilt
+      {{pointerField 0 true 0.5 0.5}}
+      ...attributes
+    >
+      <div class='pretui-tilt-plate'>
+        {{yield}}
+        {{#if this.showGlare}}
+          <span class='pretui-tilt-glare' aria-hidden='true'></span>
+        {{/if}}
+      </div>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-tilt {
+          display: inline-block;
+          perspective: var(--pretui-tilt-perspective, 900px);
+        }
+        .pretui-tilt-plate {
+          position: relative;
+          overflow: hidden;
+          transform-style: preserve-3d;
+          border-radius: var(--pretui-tilt-radius, var(--radius));
+          transform: rotateX(
+              calc(
+                -2deg * var(--pretui-ny, 0) * var(--pretui-tilt-sign, 1) *
+                  var(--pretui-tilt-max, 8)
+              )
+            )
+            rotateY(
+              calc(
+                2deg * var(--pretui-nx, 0) * var(--pretui-tilt-sign, 1) *
+                  var(--pretui-tilt-max, 8)
+              )
+            );
+          transition:
+            transform 220ms cubic-bezier(0.22, 1, 0.36, 1),
+            box-shadow 220ms ease-out,
+            scale 140ms ease-out;
+          will-change: transform;
+        }
+        .pretui-tilt[data-plate='true'] .pretui-tilt-plate {
+          background: var(--pretui-tilt-surface, var(--card));
+          box-shadow: var(
+            --pretui-shadow-card,
+            0 0 0 1px var(--border),
+            0 1px 3px rgb(16 24 40 / 0.06)
+          );
+        }
+        .pretui-tilt[data-plate='true'][data-pretui-pointer='fine']
+          .pretui-tilt-plate,
+        .pretui-tilt[data-plate='true'][data-pretui-pointer='focus']
+          .pretui-tilt-plate {
+          box-shadow: var(
+            --pretui-shadow-raised,
+            0 0 0 1px var(--border),
+            0 2px 10px rgb(16 24 40 / 0.12)
+          );
+        }
+        .pretui-tilt[data-press='true']:active .pretui-tilt-plate {
+          scale: 0.985;
+        }
+        /* a fingertip cannot see a 3D lean, and the drift reads as a bug */
+        .pretui-tilt[data-pretui-pointer='coarse'] .pretui-tilt-plate {
+          transform: none;
+        }
+        .pretui-tilt-glare {
+          position: absolute;
+          top: -30%;
+          left: -30%;
+          width: 160%;
+          height: 160%;
+          pointer-events: none;
+          background: radial-gradient(
+            circle at center,
+            color-mix(in oklch, var(--foreground) 4%, transparent) 0%,
+            transparent 58%
+          );
+          translate: calc(var(--pretui-nx, 0) * 46%)
+            calc(var(--pretui-ny, 0) * 46%);
+          transition: translate 220ms cubic-bezier(0.22, 1, 0.36, 1);
+        }
+        /* end state under reduced motion: a flat, elevated plate — the
+           resting state, not a frozen mid-tilt */
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-tilt-plate {
+            transform: none;
+            transition: box-shadow 220ms ease-out;
+          }
+          .pretui-tilt-glare {
+            display: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/tilt.md

@@ -0,0 +1,50 @@
+## What it is
+
+A perspective tilt tracking the hover position, over a real card surface.
+
+Stated plainly, because the kit's own rules name this component as the canonical cut: **an idle tilt encodes nothing.** It is decoration. It ships because five reference kits converged on it, and it earns its place on exactly two grounds, both of which are real in a still frame.
+
+## The contract
+
+```
+@max?         — maximum rotation in degrees at the corners. Default 8
+@reverse?     — invert the rotation, so the surface leans away from the pointer
+@perspective? — perspective depth in px; larger is flatter. Default 900
+@glare?       — the moving specular sheen. Default true
+@plate?       — give the tilted thing a real card surface. Default true
+@press?       — tip toward and sink at the press point. Default true
+
+<:default> — the tilted content
+```
+
+**`@plate` is the first reason to keep it.** It makes the tilted thing an actual kit surface — card radius, `--pretui-shadow-card` at rest lifting to `--pretui-shadow-raised` on engage — so a screenshot shows an elevated card with the tilt as garnish rather than a rectangle that does nothing.
+
+**`@press` is the second, and it is the only part of Tilt that encodes anything.** It tips the plate toward the _actual_ press point and sinks it, which is a real state transition: pressed, and here. If you keep one behavior, keep this one.
+
+**The default max is 8 degrees, not 15.** Upstream's 15 reads as a toy.
+
+## Prior art
+
+**motion-primitives' Tilt**, with four other kits shipping the same idea.
+
+Where Pretui is better: the resting state is a real surface rather than nothing, the press encodes the press _location_, and the rotation is dialled back to something that reads as material rather than as a gimmick.
+
+Where it is thinner: no spring or momentum on the return, no gyroscope input on touch, no per-axis maximum, and no scale-on-hover. Upstream offers a spring config; here the motion is a transition.
+
+**The honest summary:** with `@plate={{false}}` and `@press={{false}}`, this component is pure decoration with no still-frame presence, and the kit's own rules would say not to ship it. The defaults exist to keep that from happening by accident.
+
+## Accessibility
+
+- **The glare is `aria-hidden`.** It is a specular highlight, not content.
+- **The tilt adds no interaction and no keyboard surface.** Whatever is inside keeps its own; a keyboard user gets the plate and none of the motion, which is why `@plate` matters more than the tilt itself.
+- **Reduced motion should hold the plate flat.** The resting state is a card, so stopping the motion leaves a correct, complete surface rather than a frozen angle.
+- **Nothing is conveyed by the tilt.** Except the press, which is a genuine affordance — and a press that is also announced by whatever control is inside.
+- **Perspective transforms can affect text rendering.** Body copy inside a tilting plate is rasterised at an angle while it moves; keep long text out of one.
+
+## Theming
+
+`--pretui-tilt-max` (from `@max`), `--pretui-tilt-perspective` (from `@perspective`), `--pretui-tilt-sign` (from `@reverse`), `--pretui-tilt-radius` and `--pretui-tilt-surface` (the plate), plus `--pretui-shadow-card` at rest and `--pretui-shadow-raised` on engage.
+
+Using the kit's two shared shadow tokens rather than bespoke ones is what makes a tilting card lift to exactly the elevation every other card in the theme lifts to. A theme that flattens its elevation scale flattens this with it, and the tilt keeps working at whatever depth that leaves.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/tilt.usage.gts

@@ -0,0 +1,174 @@
+// Pretui — Tilt usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { Tilt } from './tilt';
+import {
+  PLACES,
+  SUPPLIERS,
+  TEAS,
+  pick,
+  seedFrom,
+} from '../examples';
+
+// ── Tilt ─────────────────────────────────────────────────────────────────
+class TiltUsage extends Component {
+  @tracked max = 8;
+  @tracked reverse = false;
+  @tracked perspective = 900;
+  @tracked glare = true;
+  @tracked plate = true;
+  @tracked press = true;
+  setMax = (v: number | null) => (this.max = v ?? 8);
+  setReverse = (v: boolean) => (this.reverse = v);
+  setPerspective = (v: number | null) => (this.perspective = v ?? 900);
+  setGlare = (v: boolean) => (this.glare = v);
+  setPlate = (v: boolean) => (this.plate = v);
+  setPress = (v: boolean) => (this.press = v);
+  get tea() {
+    return pick(seedFrom('tilt'), 0, TEAS);
+  }
+  get place() {
+    return pick(seedFrom('tilt'), 3, PLACES);
+  }
+  get supplier() {
+    return pick(seedFrom('tilt'), 5, SUPPLIERS);
+  }
+  get usage() {
+    let bits = [`@max={{${this.max}}}`];
+    if (this.reverse) bits.push('@reverse={{true}}');
+    if (this.perspective !== 900) {
+      bits.push(`@perspective={{${this.perspective}}}`);
+    }
+    if (!this.glare) bits.push('@glare={{false}}');
+    if (!this.plate) bits.push('@plate={{false}}');
+    if (!this.press) bits.push('@press={{false}}');
+    return `<Tilt ${bits.join(' ')}>\n  … card content …\n</Tilt>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Tilt'
+      @description='A perspective tilt tracking the hover position, ported from motion-primitives Tilt. Stated plainly, because Law 8 names this component as the canonical cut: AN IDLE TILT ENCODES NOTHING. It is decoration. It ships because five reference kits converged on it, and it earns its place on exactly two grounds, both real in a still frame — @plate makes the tilted thing an actual Pretui surface (card radius, --pretui-shadow-card at rest lifting to --pretui-shadow-raised on engage), so the screenshot shows an elevated card with the tilt as garnish; and @press tips the plate toward the ACTUAL press point and sinks it, which does encode a state transition (pressed, and here). If you keep one behavior of this component, keep @press. Improvements on upstream besides those: default max is 8° rather than a toy-like 15°, coarse pointers get no rotation (a tilt under a fingertip is invisible and reads as drift), focus flattens the plate so a focused control is never read at an angle, and reduced motion removes the rotation entirely — this is the most vestibular of the four — leaving the flat elevated plate as the end state.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Tilt
+          @max={{this.max}}
+          @reverse={{this.reverse}}
+          @perspective={{this.perspective}}
+          @glare={{this.glare}}
+          @plate={{this.plate}}
+          @press={{this.press}}
+        >
+          <div class='tilt-card'>
+            <p class='tilt-eyebrow'>{{this.supplier}}</p>
+            <h4 class='tilt-title'>{{this.tea}}</h4>
+            <p class='tilt-meta'>{{this.place}}
+              · 240 kg · arrives week 14</p>
+            <Button @size='xs' @appearance='outlined'>Open lot</Button>
+          </div>
+        </Tilt>
+      </:example>
+      <:api as |Args|>
+        <Args.Number
+          @name='max'
+          @defaultValue={{8}}
+          @value={{this.max}}
+          @min={{0}}
+          @max={{20}}
+          @step={{1}}
+          @description='Maximum rotation in degrees at the corners. Upstream defaults to 15, which reads as a toy; 8 reads as a surface.'
+          @onInput={{this.setMax}}
+        />
+        <Args.Bool
+          @name='reverse'
+          @defaultValue={{false}}
+          @value={{this.reverse}}
+          @description='Invert the rotation so the surface leans away from the pointer instead of toward it.'
+          @onInput={{this.setReverse}}
+        />
+        <Args.Number
+          @name='perspective'
+          @defaultValue={{900}}
+          @value={{this.perspective}}
+          @min={{300}}
+          @max={{2000}}
+          @step={{50}}
+          @description='Perspective depth in px — larger is flatter. Below ~500 the same max angle becomes cartoonish.'
+          @onInput={{this.setPerspective}}
+        />
+        <Args.Bool
+          @name='glare'
+          @defaultValue={{true}}
+          @value={{this.glare}}
+          @description='The moving specular sheen. Chrome only (Law 6) — it never carries information and is aria-hidden.'
+          @onInput={{this.setGlare}}
+        />
+        <Args.Bool
+          @name='plate'
+          @defaultValue={{true}}
+          @value={{this.plate}}
+          @description='Give the tilted thing a real Pretui card surface — radius plus elevation that lifts on engage. This is the resting state; with it off the component is invisible in a still frame and is pure decoration.'
+          @onInput={{this.setPlate}}
+        />
+        <Args.Bool
+          @name='press'
+          @defaultValue={{true}}
+          @value={{this.press}}
+          @description='Tip toward and sink at the press point on pointerdown. The one part of Tilt that encodes a state transition — it survives on touch, where the rotation does not.'
+          @onInput={{this.setPress}}
+        />
+        <Args.Yield
+          @name='default'
+          @description='The tilted content, rendered inside the plate. It keeps its own events; the glare layer is pointer-events: none and aria-hidden.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-tilt-surface'
+          @type='color'
+          @description='Plate surface color when @plate is on — defaults to the --card token.'
+        />
+        <Css.Basic
+          @name='pretui-tilt-radius'
+          @type='length'
+          @description='Plate corner radius — defaults to the --radius token.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+    <style scoped>
+      .tilt-card {
+        width: 240px;
+        padding: 16px;
+        display: grid;
+        gap: 6px;
+        justify-items: start;
+      }
+      .tilt-eyebrow {
+        margin: 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        text-transform: uppercase;
+        letter-spacing: 0.06em;
+        color: var(--muted-foreground);
+      }
+      .tilt-title {
+        margin: 0;
+        font-size: var(--text-heading-sm, 15px);
+        font-weight: 600;
+        letter-spacing: -0.02em;
+        color: var(--card-foreground);
+      }
+      .tilt-meta {
+        margin: 0 0 6px;
+        font-size: var(--text-ui-md, 12.5px);
+        font-variant-numeric: tabular-nums;
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_TILT: Record<string, unknown> = {
+  Tilt: TiltUsage,
+};