winui-svelte 0.0.3 → 0.0.5

package/src/css/translate/cascade.ts

@@ -1,5 +1,6 @@
 import type { LoweredStyle } from "./properties.ts";
 import type { Declaration, PseudoState, Rule } from "./types.ts";
+import { fontFamilySource } from "#src/font-spelling.js";
 
 /**
  * CSS's cascade for one element: which rules apply to it (its type, classes
@@ -23,6 +24,8 @@ export interface ElementFacts {
   isStarting?: boolean;
 }
 
+const FONT_FAMILY_PROPERTY = "FontFamily";
+
 /** The namespace XAML's controls, templates and styles are written in. */
 export const PRESENTATION_NAMESPACE = "http://schemas.microsoft.com/winfx/2006/xaml/presentation";
 
@@ -159,7 +162,8 @@ export function styleXaml({ key, elementType, lowered }: {
   const setters = lowered.setters.map(entry => {
     const isSetter = entry.kind === "setter";
     if (isSetter) {
-      return `  <Setter Property="${entry.property}" Value="${escapeAttribute(entry.value)}"/>`;
+      const value = entry.property === FONT_FAMILY_PROPERTY ? fontFamilySource(entry.value) : entry.value;
+      return `  <Setter Property="${entry.property}" Value="${escapeAttribute(value)}"/>`;
     }
 
     return `  <Setter Property="${entry.property}"><Setter.Value>${entry.xaml}</Setter.Value></Setter>`;

package/src/css/translate/easing.ts

@@ -162,3 +162,8 @@ export function stepLevels(easing: StepsEasing) {
   ]).get(jump);
   return Array.from({ length: count }, (_, i) => level?.(i) ?? 0);
 }
+
+/** Every timing function keyword CSS spells, `linear` included. */
+export function easingKeywords() {
+  return ["linear", ...BEZIER_KEYWORDS.keys(), ...STEP_KEYWORDS.keys()];
+}

package/src/css/translate/font-face.ts

@@ -0,0 +1,97 @@
+import type { Declaration, FontFaceRule, Severity } from "./types.ts";
+import { splitCommas } from "#src/css/parse/split.js";
+
+// `@font-face`: the family name and the font file a style sheet ships. WinUI
+// loads a file by the family name inside it, and picks the face (weight,
+// style, width) from the file itself, so the other descriptors say nothing it
+// can act on.
+
+const FAMILY = "font-family";
+const SOURCE = "src";
+const IGNORED_SILENTLY: ReadonlySet<string> = new Set(["font-display"]);
+const URL_VALUE = /^url\(\s*(?:"([^"]*)"|'([^']*)'|([^"')\s][^)]*?))\s*\)/iu;
+const QUOTED_NAME = /^(["'])(.*)\1$/u;
+const WEB_SOURCE = /^(?:https?|data|blob):/iu;
+
+/** What reading an `@font-face` found: the rule when it is usable, and what is wrong with it. */
+interface FontFaceReading {
+  face: FontFaceRule | null;
+  problems: Array<{
+    severity: Severity;
+    message: string;
+    at: Declaration["at"];
+  }>;
+}
+
+function urlOf(entry: string) {
+  const [locator = ""] = entry.trim().split(/\s+(?=format\()/iu);
+  const match = URL_VALUE.exec(locator.trim());
+  return match?.slice(1).find(group => group !== undefined) ?? null;
+}
+
+/**
+ * Reads the declarations of an `@font-face`.
+ *
+ * @param options - The declarations, and where the at-rule starts.
+ * @returns The family and the first `url()` of `src`, with the problems found.
+ */
+export function readFontFace({ declarations, at }: {
+  declarations: readonly Declaration[];
+  at: Declaration["at"];
+}) {
+  const reading: FontFaceReading = {
+    face: null,
+    problems: []
+  };
+  for (const declaration of declarations) {
+    const isUnread = ![FAMILY, SOURCE].includes(declaration.property) && !IGNORED_SILENTLY.has(declaration.property);
+    if (isUnread) {
+      reading.problems.push({
+        severity: "warning",
+        message: `@font-face ${declaration.property} has no effect: WinUI picks the face from the font file itself`,
+        at: declaration.at
+      });
+    }
+  }
+
+  const familyDeclaration = declarations.find(declaration => declaration.property === FAMILY);
+  const sourceDeclaration = declarations.find(declaration => declaration.property === SOURCE);
+  const isIncomplete = familyDeclaration === undefined || sourceDeclaration === undefined;
+  if (isIncomplete) {
+    reading.problems.push({
+      severity: "error",
+      message: "@font-face needs a font-family and a src",
+      at
+    });
+    return reading;
+  }
+
+  const family = familyDeclaration.value.trim().replace(QUOTED_NAME, "$2");
+  const sources = splitCommas(sourceDeclaration.value).map(urlOf).filter(source => source !== null);
+  const [source] = sources;
+  const isSourceMissing = source === undefined;
+  if (isSourceMissing) {
+    reading.problems.push({
+      severity: "error",
+      message: `@font-face ${family}: src needs a url() of a font file (local() names an installed font, which font-family reaches by its name)`,
+      at: sourceDeclaration.at
+    });
+    return reading;
+  }
+
+  const isWebSource = WEB_SOURCE.test(source);
+  if (isWebSource) {
+    reading.problems.push({
+      severity: "error",
+      message: `@font-face ${family}: ${source} is not a file; a font is a file next to the app`,
+      at: sourceDeclaration.at
+    });
+    return reading;
+  }
+
+  reading.face = {
+    family,
+    source
+  };
+  return reading;
+}

package/src/css/translate/handled-members.ts

@@ -0,0 +1,16 @@
+import { BUILD_GROUPS, LAZY_GROUPS } from "./lazy-groups.ts";
+import { propertyGroups } from "./properties.ts";
+
+/**
+ * Every CSS property the translation handles, longhands and shorthands, from
+ * the built-in groups, the opt-in ones and the ones the build adds: the one
+ * list the editor data and its tests are checked against.
+ */
+export function handledMembers() {
+  const groups = [
+    ...propertyGroups,
+    ...LAZY_GROUPS.flatMap(lazy => lazy.groups()),
+    ...BUILD_GROUPS.flatMap(build => build())
+  ];
+  return new Set(groups.flatMap(group => [...group.members, ...group.shorthands?.keys() ?? []]));
+}

package/src/css/translate/lazy-groups.ts

@@ -1,4 +1,4 @@
-import { ANIMATION_MEMBERS, animationGroups } from "./animation-properties.ts";
+import { ANIMATION_MEMBERS, animationGroups, TIMELINE_MEMBERS } from "./animation-properties.ts";
 import { gradientGroups } from "./background-properties.ts";
 import { buildShorthandGroups } from "./build-shorthands.ts";
 import { CLIP_MEMBERS, clipGroups } from "./clip-properties.ts";
@@ -11,11 +11,16 @@ import { POSITION_MEMBERS, positionGroups } from "./position-properties.ts";
 import type { PropertyGroup } from "./property-kit.ts";
 import { queryGroups } from "./query-properties.ts";
 import { resourceGroups } from "./resource-properties.ts";
+import { SCROLL_TIMELINE_MEMBERS, scrollTimelineGroups } from "./scroll-timeline-properties.ts";
+import { SHADOW_MEMBERS, shadowGroups } from "./shadow-properties.ts";
 import { SHAPE_MEMBERS, shapeGroups } from "./shape-properties.ts";
+import { STATE_TARGETS, VISUAL_STATE_MEMBERS } from "./state-properties.ts";
 import { SURFACE_MEMBERS, surfaceGroups } from "./surface-properties.ts";
 import { CONTROL_MEMBERS, controlGroups } from "./text-control-properties.ts";
 import { transformGroups } from "./transform-properties.ts";
 import type { Rule } from "./types.ts";
+import { TYPOGRAPHY_MEMBERS, typographyGroups } from "./typography-properties.ts";
+import { VIEW_TRANSITION_MEMBERS, viewTransitionGroups } from "./view-transition-properties.ts";
 import { VISUAL_EFFECT_MEMBERS, visualEffectGroups } from "./visual-effect-properties.ts";
 
 /**
@@ -35,6 +40,13 @@ function usesProperties(members: readonly string[]) {
   return (rule: Rule) => rule.declarations.some(declaration => members.includes(declaration.property));
 }
 
+const usesVisualStateMembers = usesProperties(VISUAL_STATE_MEMBERS);
+
+function isVisualStateRule(rule: Rule) {
+  const isStateMapped = rule.state !== null && STATE_TARGETS.has(rule.state);
+  return isStateMapped && usesVisualStateMembers(rule);
+}
+
 /** Every opt-in set; the one place that lists them (the build validates with them, a sheet module imports them). */
 export const LAZY_GROUPS: readonly LazyGroups[] = [
   {
@@ -67,6 +79,18 @@ export const LAZY_GROUPS: readonly LazyGroups[] = [
     exportName: "animationGroups",
     groups: animationGroups
   },
+  {
+    isNeededBy: usesProperties([...SCROLL_TIMELINE_MEMBERS, ...TIMELINE_MEMBERS]),
+    subpath: "/scroll-timeline",
+    exportName: "scrollTimelineGroups",
+    groups: scrollTimelineGroups
+  },
+  {
+    isNeededBy: usesProperties(VIEW_TRANSITION_MEMBERS),
+    subpath: "/view-transition",
+    exportName: "viewTransitionGroups",
+    groups: viewTransitionGroups
+  },
   {
     isNeededBy: usesProperties(EFFECT_MEMBERS),
     subpath: "/effects",
@@ -97,6 +121,24 @@ export const LAZY_GROUPS: readonly LazyGroups[] = [
     exportName: "controlGroups",
     groups: controlGroups
   },
+  {
+    isNeededBy: usesProperties(TYPOGRAPHY_MEMBERS),
+    subpath: "/typography",
+    exportName: "typographyGroups",
+    groups: typographyGroups
+  },
+  {
+    isNeededBy: usesProperties(SHADOW_MEMBERS),
+    subpath: "/shadow",
+    exportName: "shadowGroups",
+    groups: shadowGroups
+  },
+  {
+    isNeededBy: isVisualStateRule,
+    subpath: "/visual-states",
+    exportName: "visualStateGroups",
+    groups: () => []
+  },
   {
     isNeededBy: usesProperties(SHAPE_MEMBERS),
     subpath: "/shape",

package/src/css/translate/linked-tracks.ts

@@ -0,0 +1,56 @@
+import type { Track } from "./animation-tracks.ts";
+import { LinkedProperty } from "./scroll-link.ts";
+import type { LinkedTrack } from "./scroll-link.ts";
+
+// Which of an animation's tracks Composition can drive from a scroll position:
+// the ones that are a property of the element's visual (opacity, translation,
+// scale and rotation), not of the layout or of a brush.
+
+const TRANSFORM_COMPONENT = /^\(UIElement\.RenderTransform\)\.\(CompositeTransform\.(\w+)\)$/u;
+const OPACITY = "Opacity";
+const COMPOSITION_PROPERTIES: ReadonlyMap<string, LinkedProperty> = new Map([
+  [OPACITY, LinkedProperty.OPACITY],
+  ["TranslateX", LinkedProperty.TRANSLATION_X],
+  ["TranslateY", LinkedProperty.TRANSLATION_Y],
+  ["ScaleX", LinkedProperty.SCALE_X],
+  ["ScaleY", LinkedProperty.SCALE_Y],
+  ["Rotation", LinkedProperty.ROTATION]
+]);
+
+/** What a scroll-linked animation can drive, for the error that names what it cannot. */
+export const LINKABLE = "opacity, translate, scale and rotate (and a transform made of translate(), scale() and rotate())";
+
+function propertyOf(track: Track) {
+  const component = TRANSFORM_COMPONENT.exec(track.target)?.[1];
+  return COMPOSITION_PROPERTIES.get(component ?? track.target) ?? null;
+}
+
+/**
+ * The tracks as properties Composition drives, and the `Storyboard` targets of
+ * those it cannot (a width, a color, a keyword, a skew).
+ */
+export function linkedTracksOf(tracks: readonly Track[]) {
+  const linked: LinkedTrack[] = [];
+  const unsupported: string[] = [];
+  for (const track of tracks) {
+    const property = propertyOf(track);
+    const isUnsupported = property === null;
+    if (isUnsupported) {
+      unsupported.push(track.target);
+      continue;
+    }
+
+    linked.push({
+      property,
+      frames: track.frames.map(({ offset, value }) => ({
+        offset,
+        value: Number(value)
+      }))
+    });
+  }
+
+  return {
+    linked,
+    unsupported
+  };
+}

package/src/css/translate/scroll-link.ts

@@ -0,0 +1,317 @@
+import { ExpressionKind, numberText, reference, scalar } from "#src/composition/expression.js";
+import { RangeName, ScrollAxis } from "#src/css/parse/scroll-timeline.js";
+import type {
+  Offset,
+  RangePoint,
+  TimelineKind,
+  TimelineRef,
+  ViewInset
+} from "#src/css/parse/scroll-timeline.js";
+
+// The arithmetic of a scroll-linked animation, apart from WinUI so it runs
+// under `node --test`: which scroll offsets an `animation-range` spans, and the
+// Composition expressions that turn the scroll viewer's offset into the value
+// of each animated property.
+
+/** The composition properties a scroll-linked animation can drive, spelled as Composition names them. */
+export const LinkedProperty = {
+  OPACITY: "Opacity",
+  TRANSLATION_X: "Translation.X",
+  TRANSLATION_Y: "Translation.Y",
+  SCALE_X: "Scale.X",
+  SCALE_Y: "Scale.Y",
+  ROTATION: "RotationAngleInDegrees"
+} as const;
+
+/** One of the properties in `LinkedProperty`. */
+export type LinkedProperty = (typeof LinkedProperty)[keyof typeof LinkedProperty];
+
+/** The value a property has when nothing sets it. */
+export const RESTING_VALUES: ReadonlyMap<LinkedProperty, number> = new Map([
+  [LinkedProperty.OPACITY, 1],
+  [LinkedProperty.TRANSLATION_X, 0],
+  [LinkedProperty.TRANSLATION_Y, 0],
+  [LinkedProperty.SCALE_X, 1],
+  [LinkedProperty.SCALE_Y, 1],
+  [LinkedProperty.ROTATION, 0]
+]);
+
+/** The values one property takes along the animation, at offsets from 0 to 1 of its range. */
+export interface LinkedTrack {
+  readonly property: LinkedProperty;
+  readonly frames: ReadonlyArray<{
+    readonly offset: number;
+    readonly value: number;
+  }>;
+}
+
+/** What the scroll viewer and the subject measure, in pixels along the timeline's axis. */
+export interface ScrollGeometry {
+  /** The largest scroll offset: the extent minus the viewport. */
+  readonly scrollExtent: number;
+  /** The size of the viewport. */
+  readonly viewport: number;
+  /** For a view timeline, where the subject starts in the scrolled content and how big it is. */
+  readonly subject: {
+    readonly start: number;
+    readonly size: number;
+  } | null;
+  readonly inset: ViewInset;
+}
+
+/** The names the expression refers to: the scroll viewer's manipulation property set and the link's own. */
+export const ExpressionParameter = {
+  SCROLLER: "scroller",
+  LINK: "link"
+} as const;
+
+/** The scalar properties of the link's own property set. */
+export const LinkProperty = {
+  START: "Start",
+  END: "End",
+  PROGRESS: "Progress"
+} as const;
+
+const MIN_SPAN = 0.001;
+
+function resolved({ offset, whole }: {
+  offset: Offset;
+  whole: number;
+}) {
+  return offset.pixels + offset.fraction * whole;
+}
+
+function insetPixels({ inset, viewport }: {
+  inset: ViewInset["start"];
+  viewport: number;
+}) {
+  return inset.isAuto ? 0 : resolved({
+    offset: inset.offset,
+    whole: viewport
+  });
+}
+
+// The named parts of a view timeline as scroll offsets (the spec's view progress timeline).
+function viewParts({ viewport, subject, inset }: Omit<ScrollGeometry, "scrollExtent"> & {
+  subject: NonNullable<ScrollGeometry["subject"]>;
+}) {
+  const visibleStart = insetPixels({
+    inset: inset.start,
+    viewport
+  });
+  const visibleEnd = viewport - insetPixels({
+    inset: inset.end,
+    viewport
+  });
+  const isFitting = subject.size <= visibleEnd - visibleStart;
+  const enters = subject.start - visibleEnd;
+  const leaves = subject.start + subject.size - visibleStart;
+  const containStart = isFitting ? subject.start + subject.size - visibleEnd : subject.start - visibleStart;
+  const containEnd = isFitting ? subject.start - visibleStart : subject.start + subject.size - visibleEnd;
+  return new Map<RangeName, readonly [number, number]>([
+    [RangeName.COVER, [enters, leaves]],
+    [RangeName.CONTAIN, [containStart, containEnd]],
+    [RangeName.ENTRY, [enters, containStart]],
+    [RangeName.EXIT, [containEnd, leaves]],
+    [RangeName.ENTRY_CROSSING, [enters, subject.start + subject.size - visibleEnd]],
+    [RangeName.EXIT_CROSSING, [subject.start - visibleStart, leaves]]
+  ]);
+}
+
+function pointOffset({ point, parts, whole, isEnd }: {
+  point: RangePoint | null;
+  parts: ReadonlyMap<RangeName, readonly [number, number]> | null;
+  whole: readonly [number, number];
+  isEnd: boolean;
+}) {
+  const cover = parts?.get(RangeName.COVER) ?? whole;
+  const isNormal = point === null;
+  if (isNormal) {
+    return isEnd ? cover[1] : cover[0];
+  }
+
+  const [low, high] = point.name === null ? cover : parts?.get(point.name) ?? cover;
+  return low + resolved({
+    offset: point.offset,
+    whole: high - low
+  });
+}
+
+/**
+ * The scroll offsets an `animation-range` spans: the whole scroll range for a
+ * scroll timeline, the cover range of the subject for a view timeline, or the
+ * named part and offset each end writes.
+ */
+export function rangeOffsets({ geometry, start, end }: {
+  geometry: ScrollGeometry;
+  start: RangePoint | null;
+  end: RangePoint | null;
+}) {
+  const whole = [0, geometry.scrollExtent] as const;
+  const { subject } = geometry;
+  const parts = subject === null ? null : viewParts({
+    viewport: geometry.viewport,
+    subject,
+    inset: geometry.inset
+  });
+  const from = pointOffset({
+    point: start,
+    parts,
+    whole,
+    isEnd: false
+  });
+  const to = pointOffset({
+    point: end,
+    parts,
+    whole,
+    isEnd: true
+  });
+  return {
+    start: from,
+    end: Math.max(to, from + MIN_SPAN)
+  };
+}
+
+// The scroll viewer's manipulation property set and the link's own, as
+// expressions read them; the link binds both by name when it starts.
+function scrollerReference() {
+  return reference({
+    name: ExpressionParameter.SCROLLER,
+    members: {
+      translation: ExpressionKind.VECTOR3
+    }
+  });
+}
+
+function linkReference() {
+  return reference({
+    name: ExpressionParameter.LINK,
+    members: {
+      [LinkProperty.START]: ExpressionKind.SCALAR,
+      [LinkProperty.END]: ExpressionKind.SCALAR,
+      [LinkProperty.PROGRESS]: ExpressionKind.SCALAR
+    }
+  });
+}
+
+/**
+ * The expression of the link's `Progress` (0 to 1 over the animation range):
+ * the scroll viewer's offset, which is the negative of its manipulation
+ * property set's translation, between the link's `Start` and `End`, clamped.
+ * A reversed animation counts down instead.
+ */
+export function progressExpression({ axis, isReversed }: {
+  axis: ScrollAxis;
+  isReversed: boolean;
+}) {
+  const { translation } = scrollerReference();
+  const link = linkReference();
+  const start = link[LinkProperty.START];
+  const offset = (axis === ScrollAxis.HORIZONTAL ? translation.x : translation.y).negated();
+  const progress = offset.minus(start).dividedBy(link[LinkProperty.END].minus(start)).clamped({
+    min: 0,
+    max: 1
+  });
+  return isReversed ? scalar(1).minus(progress).text : progress.text;
+}
+
+/**
+ * The expression of one animated property: its key frames as straight
+ * segments over the link's `Progress`, a `Lerp` for each, clamped so that the
+ * first and last value hold outside their offsets. A track that starts after
+ * offset 0 or ends before 1 holds `underlying` (the element's own value) there.
+ */
+export function trackExpression({ track, underlying }: {
+  track: LinkedTrack;
+  underlying: number;
+}) {
+  const frames = [...track.frames].sort((first, second) => first.offset - second.offset);
+  const [first] = frames;
+  const last = frames.at(-1);
+  const isStartLate = first !== undefined && first.offset > 0;
+  const isEndEarly = last !== undefined && last.offset < 1;
+  const points = [
+    ...isStartLate ? [{
+      offset: 0,
+      value: underlying
+    }] : [],
+    ...frames,
+    ...isEndEarly ? [{
+      offset: 1,
+      value: underlying
+    }] : []
+  ];
+  const progress = linkReference()[LinkProperty.PROGRESS];
+  const segments = points.slice(1).map((point, i) => {
+    const previous = points[i];
+    const from = previous?.value ?? 0;
+    const span = point.offset - (previous?.offset ?? 0);
+    const isFirst = i === 0;
+    const amount = progress.minus(previous?.offset ?? 0).dividedBy(Math.max(span, MIN_SPAN)).clamped({
+      min: 0,
+      max: 1
+    });
+    return scalar(isFirst ? from : 0).lerp({
+      to: isFirst ? point.value : point.value - from,
+      amount
+    });
+  });
+  const [head, ...rest] = segments;
+  const isEmpty = head === undefined;
+  if (isEmpty) {
+    return numberText(underlying);
+  }
+
+  let sum = head;
+  for (const segment of rest) {
+    sum = sum.plus(segment);
+  }
+
+  return sum.text;
+}
+
+/** One animation linked to a scroll or view timeline, resolved by the build. */
+export interface LinkedAnimation {
+  readonly timeline: Exclude<TimelineRef, { readonly kind: typeof TimelineKind.AUTO | typeof TimelineKind.NONE }>;
+  readonly start: RangePoint | null;
+  readonly end: RangePoint | null;
+  readonly isReversed: boolean;
+  readonly tracks: readonly LinkedTrack[];
+}
+
+/** A timeline an element defines for its descendants: `scroll-timeline-name` or `view-timeline-name`. */
+export interface TimelineDefinition {
+  readonly name: string;
+  readonly kind: typeof TimelineKind.SCROLL | typeof TimelineKind.VIEW;
+  readonly axis: ScrollAxis;
+  readonly inset: ViewInset;
+}
+
+// What the build lowered, by the text the write carries: the write is a string,
+// and the runtime that applies it is the one that lowered it.
+const linkedByText = new Map<string, readonly LinkedAnimation[]>();
+const definitionByText = new Map<string, TimelineDefinition>();
+
+/** The write value for the animations linked to timelines. */
+export function writeLinked(links: readonly LinkedAnimation[]) {
+  const text = JSON.stringify(links);
+  linkedByText.set(text, links);
+  return text;
+}
+
+/** The animations a `writeLinked` value stands for. */
+export function readLinked(text: string) {
+  return linkedByText.get(text) ?? [];
+}
+
+/** The write value for a timeline definition. */
+export function writeDefinition(definition: TimelineDefinition) {
+  const text = JSON.stringify(definition);
+  definitionByText.set(text, definition);
+  return text;
+}
+
+/** The definition a `writeDefinition` value stands for. */
+export function readDefinition(text: string) {
+  return definitionByText.get(text) ?? null;
+}