@jomae/catalog 0.1.0

package/dist/rules/view-transitions.js

@@ -0,0 +1,53 @@
+export const viewTransitions = {
+    id: "view-transitions",
+    title: "Page and state transitions",
+    replaces: [
+        "next-view-transitions",
+        "react-page-transition",
+        "barba.js",
+        "swup",
+    ],
+    featureIds: ["view-transitions"],
+    native: "The View Transitions API",
+    human: {
+        explainer: "The browser snapshots the old and new state and cross-fades between them, so a transition no longer means keeping the outgoing DOM mounted while you animate it out. Matching view-transition-name values on both sides give you a shared element transition, where a thumbnail grows into a hero image. For same-document transitions this is well supported; the cross-document version that makes multi-page apps animate is newer, so check it separately.",
+        snippet: `/* Same-document: wrap the state change. */
+document.startViewTransition(() => {
+  applyTheNewState();
+});
+
+/* Shared element: same name on both pages. */
+.thumbnail,
+.hero-image {
+  view-transition-name: hero;
+}
+
+/* Customise the default cross-fade. */
+::view-transition-old(hero) {
+  animation-duration: 0.3s;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(*) {
+    animation: none;
+  }
+}`,
+    },
+    agent: {
+        when: "cross-fading between two states, or growing a thumbnail into a hero image across a navigation",
+        unless: [
+            "You need cross-document transitions in a multi-page app. That part is less supported than same-document transitions, so verify it separately rather than assuming the whole API is available.",
+            "Your framework's router needs the outgoing page kept mounted, or its data fetching happens after the navigation commits, which leaves nothing to snapshot.",
+            "You need two elements with the same view-transition-name visible at once. Names must be unique per transition or it throws.",
+            "You need to interrupt or reverse a transition partway, for example following a swipe-back gesture.",
+            "You need the transition on a long list where every item has a name, which gets expensive.",
+        ],
+        snippet: `document.startViewTransition(() => applyNewState());
+
+.thumb, .hero { view-transition-name: hero; }
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(*) { animation: none; }
+}`,
+    },
+};
+//# sourceMappingURL=view-transitions.js.map

package/dist/rules/view-transitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-transitions.js","sourceRoot":"","sources":["../../src/rules/view-transitions.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,eAAe,GAAS;IACnC,EAAE,EAAE,kBAAkB;IACtB,KAAK,EAAE,4BAA4B;IACnC,QAAQ,EAAE;QACR,uBAAuB;QACvB,uBAAuB;QACvB,UAAU;QACV,MAAM;KACP;IACD,UAAU,EAAE,CAAC,kBAAkB,CAAC;IAChC,MAAM,EAAE,0BAA0B;IAClC,KAAK,EAAE;QACL,SAAS,EACP,gcAAgc;QAClc,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;EAoBX;KACC;IACD,KAAK,EAAE;QACL,IAAI,EAAE,+FAA+F;QACrG,MAAM,EAAE;YACN,+LAA+L;YAC/L,4JAA4J;YAC5J,6HAA6H;YAC7H,oGAAoG;YACpG,2FAA2F;SAC5F;QACD,OAAO,EAAE;;;;;EAKX;KACC;CACF,CAAC"}

package/dist/schema.d.ts

@@ -0,0 +1,91 @@
+import { z } from "zod";
+/**
+ * Bumped whenever the shape of a rule changes in a way that breaks consumers.
+ * Published alongside the catalog so downstream surfaces can refuse data they
+ * do not understand.
+ */
+export declare const SCHEMA_VERSION = 1;
+/**
+ * Support tiers, mirroring the three Baseline states plus an explicit unknown.
+ * `unknown` is never authored by hand. It only appears when a `featureId` is
+ * missing from the web-features snapshot, which the catalog tests treat as a
+ * failure.
+ */
+export declare const baselineStatusSchema: z.ZodEnum<{
+    limited: "limited";
+    newly: "newly";
+    unknown: "unknown";
+    widely: "widely";
+}>;
+export type BaselineStatus = z.infer<typeof baselineStatusSchema>;
+/**
+ * Escape hatch for features that web-features has no ID for yet. Carries the
+ * date it was checked by hand so `scripts/check-freshness.ts` can fail CI once
+ * the claim goes stale.
+ */
+export declare const manualBaselineSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        limited: "limited";
+        newly: "newly";
+        widely: "widely";
+    }>;
+    verifiedOn: z.ZodString;
+    note: z.ZodString;
+}, z.core.$strip>;
+export type ManualBaseline = z.infer<typeof manualBaselineSchema>;
+export declare const ruleSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    replaces: z.ZodArray<z.ZodString>;
+    featureIds: z.ZodArray<z.ZodString>;
+    native: z.ZodString;
+    human: z.ZodObject<{
+        explainer: z.ZodString;
+        snippet: z.ZodString;
+        demoUrl: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>;
+    agent: z.ZodObject<{
+        when: z.ZodString;
+        unless: z.ZodArray<z.ZodString>;
+        snippet: z.ZodString;
+    }, z.core.$strip>;
+    manualBaseline: z.ZodOptional<z.ZodObject<{
+        status: z.ZodEnum<{
+            limited: "limited";
+            newly: "newly";
+            widely: "widely";
+        }>;
+        verifiedOn: z.ZodString;
+        note: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Rule = z.infer<typeof ruleSchema>;
+export declare const catalogSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    replaces: z.ZodArray<z.ZodString>;
+    featureIds: z.ZodArray<z.ZodString>;
+    native: z.ZodString;
+    human: z.ZodObject<{
+        explainer: z.ZodString;
+        snippet: z.ZodString;
+        demoUrl: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>;
+    agent: z.ZodObject<{
+        when: z.ZodString;
+        unless: z.ZodArray<z.ZodString>;
+        snippet: z.ZodString;
+    }, z.core.$strip>;
+    manualBaseline: z.ZodOptional<z.ZodObject<{
+        status: z.ZodEnum<{
+            limited: "limited";
+            newly: "newly";
+            widely: "widely";
+        }>;
+        verifiedOn: z.ZodString;
+        note: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+/** Throws a readable error if any rule is malformed. Used by tests and CI. */
+export declare function parseCatalog(rules: unknown): Rule[];
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;EAK/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAkBlE;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;iBAK/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;iBA0DnB,CAAC;AAEL,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAE9C,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;kBA2BxB,CAAC;AAEH,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,EAAE,CAEnD"}

package/dist/schema.js

@@ -0,0 +1,124 @@
+import { z } from "zod";
+/**
+ * Bumped whenever the shape of a rule changes in a way that breaks consumers.
+ * Published alongside the catalog so downstream surfaces can refuse data they
+ * do not understand.
+ */
+export const SCHEMA_VERSION = 1;
+/**
+ * Support tiers, mirroring the three Baseline states plus an explicit unknown.
+ * `unknown` is never authored by hand. It only appears when a `featureId` is
+ * missing from the web-features snapshot, which the catalog tests treat as a
+ * failure.
+ */
+export const baselineStatusSchema = z.enum([
+    "widely",
+    "newly",
+    "limited",
+    "unknown",
+]);
+const isoDate = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, "expected an ISO date, YYYY-MM-DD");
+const slug = z
+    .string()
+    .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "expected a lowercase kebab-case slug");
+/** npm package names: optionally scoped, lowercase, no URL-unsafe characters. */
+const packageName = z
+    .string()
+    .regex(/^(?:@[a-z0-9][a-z0-9-._]*\/)?[a-z0-9][a-z0-9-._]*$/, "expected a lowercase npm package name");
+/**
+ * Escape hatch for features that web-features has no ID for yet. Carries the
+ * date it was checked by hand so `scripts/check-freshness.ts` can fail CI once
+ * the claim goes stale.
+ */
+export const manualBaselineSchema = z.object({
+    status: baselineStatusSchema.exclude(["unknown"]),
+    verifiedOn: isoDate,
+    /** What was checked, and where. Shown to maintainers, not to users. */
+    note: z.string().min(1),
+});
+export const ruleSchema = z
+    .object({
+    /** Stable identifier. Used in URLs and as the reference filename. */
+    id: slug,
+    /** Short human label, e.g. "Carousels". */
+    title: z.string().min(1),
+    /** npm packages this rule can replace. Exact names, lowercase. */
+    replaces: z.array(packageName).min(1),
+    /**
+     * web-features IDs for the features REQUIRED to make the replacement.
+     * Baseline status is DERIVED from these, never hardcoded, and a rule
+     * reports the least-supported of them. Features that merely make the
+     * snippet nicer do not belong here, or they would understate the rule.
+     * Call those out in `agent.unless` instead. Empty only when
+     * `manualBaseline` is supplied.
+     */
+    featureIds: z.array(z.string().min(1)),
+    /** The native approach, one line. */
+    native: z.string().min(1),
+    human: z.object({
+        /** 2 to 4 sentences of prose. */
+        explainer: z.string().min(1),
+        /** Copy-pasteable CSS or HTML. */
+        snippet: z.string().min(1),
+        /** A live demo or a post that walks through it. */
+        demoUrl: z.url().optional(),
+    }),
+    /** Terse projection for LLM surfaces. Budget roughly 200 tokens. */
+    agent: z.object({
+        /** The situation the native approach covers. */
+        when: z.string().min(1),
+        /**
+         * The refusal conditions: when the dependency is still the right call.
+         * A rule with an empty `unless` is not finished, so this is enforced
+         * rather than documented.
+         */
+        unless: z
+            .array(z.string().min(1))
+            .min(1, "every rule must state when the dependency is still correct"),
+        snippet: z.string().min(1),
+    }),
+    manualBaseline: manualBaselineSchema.optional(),
+})
+    .superRefine((rule, ctx) => {
+    if (rule.featureIds.length === 0 && !rule.manualBaseline) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["featureIds"],
+            message: "a rule needs at least one web-features ID, or an explicit manualBaseline with a verifiedOn date",
+        });
+    }
+});
+export const catalogSchema = z.array(ruleSchema).superRefine((rules, ctx) => {
+    const seenIds = new Set();
+    const owners = new Map();
+    for (const [index, rule] of rules.entries()) {
+        if (seenIds.has(rule.id)) {
+            ctx.addIssue({
+                code: "custom",
+                path: [index, "id"],
+                message: `duplicate rule id "${rule.id}"`,
+            });
+        }
+        seenIds.add(rule.id);
+        for (const pkg of rule.replaces) {
+            const owner = owners.get(pkg);
+            if (owner) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: [index, "replaces"],
+                    message: `"${pkg}" is already claimed by rule "${owner}". A package may only be claimed once, so a report never shows the same dependency twice.`,
+                });
+            }
+            else {
+                owners.set(pkg, rule.id);
+            }
+        }
+    }
+});
+/** Throws a readable error if any rule is malformed. Used by tests and CI. */
+export function parseCatalog(rules) {
+    return catalogSchema.parse(rules);
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@jomae/catalog",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "The rule catalog behind youmightnotneed.dev. Maps npm packages to the modern CSS and HTML that replaces them.",
+  "license": "MIT",
+  "author": "Johannes Maendle",
+  "homepage": "https://youmightnotneed.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jomaendle/youmightnotneed.git",
+    "directory": "packages/catalog"
+  },
+  "keywords": [
+    "css",
+    "baseline",
+    "bundle-size",
+    "web-platform",
+    "dependencies"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.11",
+    "@types/node": "^24.13.3",
+    "@vitest/coverage-v8": "^4.1.11"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}