@gryt/theme 0.8.0 → 0.9.0

package/dist/theme.d.ts

@@ -3,11 +3,115 @@ export type GrytAppearance = "dark" | "light";
 export declare const GRYT_HUE_KEYS: readonly ["accent", "accentLight", "secondary", "secondaryLight", "success", "danger", "dangerLight", "warning", "onAccent", "onSecondary", "onDanger"];
 export declare const GRYT_NEUTRAL_KEYS: readonly ["bg", "surface", "surfaceRaised", "surfaceHover", "border", "muted", "text"];
 export declare const GRYT_RADIUS_KEYS: readonly ["sm", "md", "lg", "xl", "full"];
+/**
+ * The three jobs a typeface does here.
+ *
+ * Three because that is what the interface actually distinguishes: the text
+ * you read, the headings above it, and the places where characters have to
+ * line up — code, hex values, timestamps, a fingerprint read aloud. Finer than
+ * that is a knob nobody turns, and coarser loses the one distinction that
+ * matters, which is that a proportional face cannot do the third job.
+ */
+export declare const GRYT_FONT_KEYS: readonly ["body", "display", "mono"];
+/**
+ * How a theme is allowed to change the way Gryt moves.
+ *
+ * Two things, because they are the two a person can answer. How fast, which is
+ * one number over every tier, and what shape, which is one curve.
+ *
+ * Not per-tier durations. The tiers are already in proportion to each other —
+ * a drawer takes longer than a button because it travels further — and a
+ * theme that set them independently would be re-deciding a relationship
+ * somebody worked out once, five sliders at a time, with no way to tell it had
+ * gone wrong except by opening a drawer.
+ *
+ * `scale` at 0 means nothing animates. That is a real setting rather than a
+ * degenerate one: some people find movement unpleasant, and the honest way to
+ * offer that is a value in the theme rather than asking them to lie to their
+ * operating system about `prefers-reduced-motion`.
+ */
+export declare const GRYT_MOTION_CURVES: readonly ["spring", "smooth", "linear"];
 export type GrytHueKey = (typeof GRYT_HUE_KEYS)[number];
 export type GrytNeutralKey = (typeof GRYT_NEUTRAL_KEYS)[number];
 export type GrytRadiusKey = (typeof GRYT_RADIUS_KEYS)[number];
+export type GrytFontKey = (typeof GRYT_FONT_KEYS)[number];
+export type GrytNamedCurve = (typeof GRYT_MOTION_CURVES)[number];
+/** x1, y1, x2, y2 — the two control points of a cubic bezier. */
+export type GrytBezier = readonly [number, number, number, number];
+export type GrytMotionCurve = GrytNamedCurve | GrytBezier;
 export type GrytHues = Record<GrytHueKey, string>;
 export type GrytNeutrals = Record<GrytNeutralKey, string>;
+/**
+ * A whole CSS font stack per role, not a family name.
+ *
+ * The fallbacks are the point. A theme names a face the machine reading it may
+ * not have — that is the ordinary case for anything a shared link asks for —
+ * and what it falls back to decides whether the note reads as a different
+ * choice or as a broken one. Carrying the stack means the theme's author picks
+ * that, rather than every consumer inventing its own tail.
+ */
+export type GrytFonts = Record<GrytFontKey, string>;
+/**
+ * What the library is set in.
+ *
+ * Atkinson Hyperlegible, which is a legibility face rather than a taste one:
+ * its letterforms are drawn to be told apart at a glance, and Gryt is read in
+ * a sidebar at twelve pixels. `display` is the body face here — the default
+ * theme does not set headings in anything else, and a default that quietly
+ * differed from what ships would be a second thing to keep in step.
+ */
+export declare const grytFonts: GrytFonts;
+/**
+ * The motion half of a theme.
+ *
+ * `curve` names one of the shipped shapes or carries a cubic bezier.
+ *
+ * A named curve keeps the library's two apart: `--ease-spring` overshoots and
+ * is for things that scale in place, `--ease-spring-tight` does not and is for
+ * things that travel inside their bounds. A bezier cannot express both, so
+ * setting one collapses them into a single shape — which is the honest cost of
+ * letting a theme draw its own, and is worth knowing before drawing one that
+ * overshoots.
+ */
+export interface GrytMotion {
+    /**
+     * Multiplier on every duration. 0 is no animation at all.
+     *
+     * One number rather than five, so the tiers keep the proportions they were
+     * given. The curves are duration-invariant — measured, not assumed: the same
+     * `linear()` sampled at 200ms and at 2000ms puts the element in the same
+     * place at every fraction of the animation, and peaks at the same 10.6% past
+     * its target — so scaling time changes how long it takes and nothing else
+     * about how it looks.
+     */
+    scale: number;
+    curve: GrytMotionCurve;
+}
+export declare const grytMotion: GrytMotion;
+/** Past this and it is somebody testing rather than choosing. */
+export declare const GRYT_MOTION_SCALE_MAX = 3;
+export declare function isBezier(curve: GrytMotionCurve): curve is GrytBezier;
+/**
+ * A bezier CSS will accept.
+ *
+ * The x values are the time axis and have to stay inside it; a control point
+ * outside 0..1 horizontally is not a slower curve, it is an invalid one and
+ * the whole declaration is dropped. The y values may go outside, which is how
+ * a bezier overshoots, and that is allowed on purpose.
+ */
+export declare function isValidBezier(value: unknown): value is GrytBezier;
+/** Long enough for a real stack, short enough not to be a payload. */
+export declare const GRYT_FONT_STACK_MAX = 200;
+/**
+ * A font stack that is safe to put in a stylesheet.
+ *
+ * This arrives from a link somebody was sent, so it is a string from a
+ * stranger heading for a CSS declaration. Anything that could close the
+ * declaration and start another one is refused outright rather than escaped —
+ * a font stack has no legitimate use for a brace, a semicolon or a comment
+ * marker, so there is nothing to lose by requiring it to look like one.
+ */
+export declare function isFontStack(value: string): boolean;
 export interface GrytTheme {
     /**
      * What its author called it, if they called it anything.
@@ -24,6 +128,14 @@ export interface GrytTheme {
     dark: GrytNeutrals;
     light: GrytNeutrals;
     radius: Record<GrytRadiusKey, number>;
+    /**
+     * Null when the theme does not care, which is every theme written before
+     * this existed and every link already shared. Absent means the library's
+     * own, so nothing that predates fonts renders differently for having them.
+     */
+    fonts?: GrytFonts | null;
+    /** Null for the library's own motion, same reasoning as `fonts`. */
+    motion?: GrytMotion | null;
 }
 /** Long enough for a name, short enough not to be a payload. */
 export declare const GRYT_THEME_NAME_MAX = 60;

package/dist/theme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9C,eAAO,MAAM,aAAa,yJAYhB,CAAC;AAEX,eAAO,MAAM,iBAAiB,wFAQpB,CAAC;AAEX,eAAO,MAAM,gBAAgB,2CAA4C,CAAC;AAE1E,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AACxD,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAChE,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;AAClD,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;AAE1D,MAAM,WAAW,SAAS;IACxB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,QAAQ,CAAC;IACd,uEAAuE;IACvE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1B,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;CACvC;AAED,gEAAgE;AAChE,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,6CAA6C;AAC7C,eAAO,MAAM,SAAS,EAAE,SAkCvB,CAAC;AAEF,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAS1D;AAED,wCAAwC;AACxC,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,EAChB,UAAU,EAAE,cAAc,GACzB,QAAQ,CAIV;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,EAChB,UAAU,EAAE,cAAc,GACzB,gBAAgB,CAMlB;AA8BD,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKvD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,EAChB,UAAU,CAAC,EAAE,cAAc,GAC1B,eAAe,CAoCjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,SAAS,CAAC;IACjB,wEAAwE;IACxE,UAAU,EAAE,cAAc,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAOtE"}
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gryt/theme",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Gryt's design tokens, colour scales and OKLCH maths. No renderer, no DOM.",
   "type": "module",
   "license": "MIT",