@kadal/theme-lecture 0.0.0-stage → 0.4.1

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# @kadal/theme-lecture
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Lecture**, a theme for [Kadal Deck](https://deck.kadal.cc). An academic theme for lectures, seminars and defences. The Source family (Serif 4 for headings, Sans 3 for text, Code Pro for code), navy for structure and crimson for results, numbered sections, a footer on every slide, definition / theorem / proof blocks set the way a textbook sets them, citations, and a references layout. Made to print: white pages, hairlines that survive a laser printer, no shadows, the footer on every page.
+
+![Lecture: the cover, a content slide, code and the theme's own layout](./screenshot.jpg)
+
+## Use it
+
+```bash
+npm install @kadal/theme-lecture
+```
+
+```yaml
+---
+theme: lecture
+themeConfig:            # all optional
+  footer: true
+  sectionNumbers: true
+  accent: "#1f4e8c"
+---
+```
+
+The deck plugin brings the stylesheet and the module in; nothing to import. The prebuilt shell (the hosted builder, published decks) bundles this theme already. Schemes: light and dark. Fonts: Source Serif 4 (headings, serif), Source Sans 3 (text), Source Code Pro (code), loaded through the theme's `config.fonts`. Code colours: Shiki's github-light / github-dark-dimmed. To show it beside other themes in the theme menu (<kbd>T</kbd>), list it: `themes: [lecture, minimal]`.
+
+## themeConfig
+
+Every key arrives on the deck root as a CSS variable (`accentDark` → `--theme-accent-dark`); the theme reads them with fallbacks, so set only what you change.
+
+| key | type | default | what it does |
+| --- | --- | --- | --- |
+| `course` | string | — | The course, bold at the footer's left ("MA 201 · Linear Algebra"). |
+| `author` | string | the deck's `author` | Who is speaking, after the course. |
+| `institution` | string | — | After the author. |
+| `footer` | boolean | `true` | `false` turns the footer off; `footer: false` on a slide hides it there. |
+| `sectionNumbers` | boolean | `true` | `false` leaves the numbers off section slides and the footer. |
+| `accent` | colour | `#1f4e8c` | The colour of the structure (headings' rules, numbers, definitions). |
+
+## Layouts
+
+Every built-in layout is styled (`default`, `center`, `cover`, `intro`, `section`, `end`, `fact`, `quote`, `statement`, `full`, `two-cols`, `two-cols-header`, `image`, `image-left`, `image-right`, `iframe`, `iframe-left`, `iframe-right`), and the theme adds:
+
+| layout | what |
+| --- | --- |
+| `section` | The built-in section, numbered: "Section 2" over the title, counted from the deck's section slides (`n:` overrides). |
+| `definition` | A slide that is one definition, large: `name:` and `n:` label it. |
+| `theorem` | The same for a theorem; `kind: lemma | corollary | proposition`. |
+| `references` | The slide's list as a numbered bibliography, [1] [2] …, in two columns past six entries. |
+
+## Components
+
+| component | what |
+| --- | --- |
+| `<Definition>` `<Theorem>` `<Lemma>` `<Corollary>` `<Proposition>` `<Example>` `<Remark>` | A run-in label ("Theorem 2.1 (Pythagoras).") then the body: `n` numbers it, `title` names it. A definition is a tinted box, a theorem (and lemma, corollary, proposition) a frame with the statement in italics. |
+| `<Proof of>` | "Proof." (or "Proof of Theorem 2.1.") then the body, closed with ∎. |
+| `<Cite n page />` | `[3]`, `[3, 7, p. 12]`; with children, author–year: `<Cite>Knuth 1984</Cite>` → (Knuth 1984). |
+
+## Preview
+
+`preview/deck.mdx` walks through every layout and component (`theme: ../`). In this repository:
+
+```bash
+bun run --filter @kadal/theme-lecture dev       # the preview deck, live
+node tools/theme-shots.mjs lecture               # screenshots in light and dark, contrast and overflow checks
+```
+
+## Accessibility and print
+
+Body and muted text meet WCAG AA (4.5:1) on the page and on cards in every scheme the theme draws (checked by `tools/theme-shots.mjs`). Anything that moves stands still under `prefers-reduced-motion` and on a still copy; printed pages and exports drop shadows and glows.
+
+## Licence
+
+AGPL-3.0-or-later, like the engine (see LICENSE); a commercial licence is available — see [LICENSING](https://github.com/kadalcc/deck/blob/main/LICENSING.md).

package/index.tsx

@@ -0,0 +1,245 @@
+import type { ReactNode } from "react";
+
+import { type LayerProps, type LayoutProps, useDeck, useSlideOptional } from "@kadal/deck";
+
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Lecture's module: the footer, numbered sections, the blocks a textbook sets, citations.
+ *
+ *   the footer          a slide-bottom layer on every slide but the cover: the course (bold),
+ *                       the author and the institution; the current section; "page / total".
+ *                       `themeConfig.footer: false` turns it off, `footer: false` on a slide
+ *                       hides it there. It is drawn on printed pages too.
+ *   layout: section     the built-in section, numbered: "Section 2" over the title (counted
+ *                       from the deck's section slides; `n:` overrides, and
+ *                       `themeConfig.sectionNumbers: false` leaves them off)
+ *   layout: definition  a slide that is one definition, large: `name:` and `n:` label it
+ *   layout: theorem     the same for a theorem (`kind: lemma | corollary | proposition`)
+ *   layout: references  the slide's list as a numbered bibliography, [1] [2] …, two columns
+ *                       past six entries
+ *   <Definition> <Theorem> <Lemma> <Corollary> <Proposition> <Example> <Remark>
+ *                       a run-in label ("Theorem 2.1 (Pythagoras).") then the body; `n` numbers
+ *                       it, `title` names it
+ *   <Proof>             "Proof." … ∎   (`of="Theorem 2.1"` → "Proof of Theorem 2.1.")
+ *   <Cite n={3} />      [3]   (`n="3, 7"`, `page="12"` → [3, 7, p. 12]); with children, the
+ *                       author-year form: <Cite>Knuth 1984</Cite> → (Knuth 1984)
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+
+const DEFAULTS = {
+  course: "",
+  author: "",
+  institution: "",
+  footer: true,
+  sectionNumbers: true,
+};
+
+const str = (v: unknown) => (typeof v === "string" && v.trim() ? v.trim() : null);
+const label = (v: unknown) => (v == null || v === "" ? null : String(v).trim());
+
+/** The theme's settings: its defaults under the deck's `themeConfig`. */
+function useLectureConfig() {
+  const deck = useDeck();
+  return { ...DEFAULTS, ...deck.config.themeConfig } as typeof DEFAULTS & Record<string, unknown>;
+}
+
+/** The section a slide is in: its number and title, from the deck's `layout: section` slides. */
+function useSectionOf(index: number): { n: number; title: string | null } | null {
+  const deck = useDeck();
+  const sections = deck.manifest.slides.filter(
+    (s) => s.index <= index && s.frontmatter.layout === "section",
+  );
+  const last = sections.at(-1);
+  if (!last) return null;
+  const given = label(last.frontmatter.n);
+  return { n: given && /^\d+$/.test(given) ? Number(given) : sections.length, title: last.title };
+}
+
+function Footer({ slide, page, total, layout, frontmatter }: LayerProps) {
+  const deck = useDeck();
+  const cfg = useLectureConfig();
+  const section = useSectionOf(slide?.index ?? 0);
+  if (cfg.footer === false || frontmatter.footer === false || layout === "cover") return null;
+  const course = str(cfg.course);
+  const rest = [str(cfg.author) ?? str(deck.config.author), str(cfg.institution)].filter(Boolean);
+  return (
+    <footer className="lecture-footer" aria-hidden="true">
+      <span>
+        {course ? <b>{course}</b> : null}
+        {course && rest.length ? " · " : null}
+        {rest.join(" · ")}
+      </span>
+      <span className="lecture-footer-section">
+        {section?.title
+          ? `${cfg.sectionNumbers === false ? "" : `${section.n}  `}${section.title}`
+          : ""}
+      </span>
+      <span className="lecture-footer-page">
+        {page} / {total}
+      </span>
+    </footer>
+  );
+}
+
+function Section({ children, frontmatter }: LayoutProps) {
+  const cfg = useLectureConfig();
+  const index = useSlideOptional()?.meta.index ?? 0;
+  const section = useSectionOf(index);
+  const n = label(frontmatter.n) ?? (section ? String(section.n) : null);
+  return (
+    <div className="deck-layout deck-layout-section">
+      {cfg.sectionNumbers !== false && n ? (
+        <div className="lecture-section-number">
+          Section <b>{n}</b>
+        </div>
+      ) : null}
+      {children}
+    </div>
+  );
+}
+
+type Kind =
+  | "definition"
+  | "theorem"
+  | "lemma"
+  | "corollary"
+  | "proposition"
+  | "proof"
+  | "example"
+  | "remark";
+
+const NAMES: Record<Kind, string> = {
+  definition: "Definition",
+  theorem: "Theorem",
+  lemma: "Lemma",
+  corollary: "Corollary",
+  proposition: "Proposition",
+  proof: "Proof",
+  example: "Example",
+  remark: "Remark",
+};
+
+interface BlockProps {
+  n?: string | number;
+  title?: string;
+  /** Proof only: what it proves ("Theorem 2.1"). */
+  of?: string;
+  children?: ReactNode;
+}
+
+function Block({ kind, n, title, of, children }: BlockProps & { kind: Kind }) {
+  const name = kind === "proof" && of ? `Proof of ${of}` : NAMES[kind];
+  const num = label(n);
+  return (
+    <div className={`lecture-block is-${kind}`} role="note" aria-label={name}>
+      <div className="lecture-block-body">
+        <span className="lecture-label">
+          {name}
+          {num ? ` ${num}` : ""}
+          {title ? (
+            <>
+              {" "}
+              <i>({title})</i>
+            </>
+          ) : null}
+          .{" "}
+        </span>
+        {children}
+      </div>
+    </div>
+  );
+}
+
+const block = (kind: Kind) =>
+  function LectureBlock(props: BlockProps) {
+    return <Block kind={kind} {...props} />;
+  };
+
+const Definition = block("definition");
+const Theorem = block("theorem");
+const Lemma = block("lemma");
+const Corollary = block("corollary");
+const Proposition = block("proposition");
+const Proof = block("proof");
+const Example = block("example");
+const Remark = block("remark");
+
+function DefinitionLayout({ children, frontmatter }: LayoutProps) {
+  return (
+    <div className="deck-layout deck-layout-definition">
+      <Block
+        kind="definition"
+        n={label(frontmatter.n) ?? undefined}
+        title={str(frontmatter.name) ?? undefined}
+      >
+        {children}
+      </Block>
+    </div>
+  );
+}
+
+function TheoremLayout({ children, frontmatter }: LayoutProps) {
+  const k = str(frontmatter.kind);
+  const kind: Kind = k === "lemma" || k === "corollary" || k === "proposition" ? k : "theorem";
+  return (
+    <div className="deck-layout deck-layout-theorem">
+      <Block
+        kind={kind}
+        n={label(frontmatter.n) ?? undefined}
+        title={str(frontmatter.name) ?? undefined}
+      >
+        {children}
+      </Block>
+    </div>
+  );
+}
+
+function References({ children }: LayoutProps) {
+  return <div className="deck-layout deck-layout-references">{children}</div>;
+}
+
+function Cite({
+  n,
+  page,
+  children,
+}: {
+  n?: string | number;
+  page?: string | number;
+  children?: ReactNode;
+}) {
+  const p = label(page);
+  if (children != null && n == null)
+    return (
+      <span className="lecture-cite">
+        ({children}
+        {p ? `, p. ${p}` : ""})
+      </span>
+    );
+  return (
+    <span className="lecture-cite">
+      [{label(n) ?? "?"}
+      {p ? `, p. ${p}` : ""}]
+    </span>
+  );
+}
+
+export default {
+  layouts: {
+    section: Section,
+    definition: DefinitionLayout,
+    theorem: TheoremLayout,
+    references: References,
+  },
+  components: {
+    Definition,
+    Theorem,
+    Lemma,
+    Corollary,
+    Proposition,
+    Proof,
+    Example,
+    Remark,
+    Cite,
+  },
+  layers: { "slide-bottom": Footer },
+};

package/package.json

@@ -1,6 +1,118 @@
 {
   "name": "@kadal/theme-lecture",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.1",
+  "description": "Lecture, a theme for Kadal Deck (@kadal/deck). An academic theme for lectures and seminars: numbered sections, a course footer, theorem, definition and proof blocks, citations, and print-perfect pages.",
+  "keywords": [
+    "kadal-theme",
+    "kadal-deck",
+    "presentation",
+    "slides",
+    "theme",
+    "academic",
+    "lecture",
+    "education",
+    "math"
+  ],
+  "homepage": "https://deck.kadal.cc/docs/",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/pmithunish"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kadalcc/deck.git",
+    "directory": "packages/theme-lecture"
+  },
+  "bugs": {
+    "url": "https://github.com/kadalcc/deck/issues"
+  },
+  "license": "AGPL-3.0-or-later",
+  "author": "Mithunish Prabhakaran <pmithunish@gmail.com>",
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "style.css",
+    "index.tsx",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./index.tsx",
+    "./style.css": "./style.css",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "kadal": {
+    "theme": {
+      "name": "lecture",
+      "title": "Lecture",
+      "description": "An academic theme for lectures and seminars: numbered sections, a course footer, theorem, definition and proof blocks, citations, and print-perfect pages.",
+      "colorScheme": "both",
+      "config": {
+        "transition": "fade",
+        "fonts": {
+          "heading": "Source Serif 4",
+          "sans": "Source Sans 3",
+          "serif": "Source Serif 4",
+          "mono": "Source Code Pro",
+          "weights": "400,600,700",
+          "italic": true
+        }
+      },
+      "themeConfig": {
+        "course": "",
+        "author": "",
+        "institution": "",
+        "footer": true,
+        "sectionNumbers": true
+      },
+      "shiki": {
+        "light": "github-light",
+        "dark": "github-dark-dimmed"
+      },
+      "defaults": {},
+      "layouts": [
+        "section",
+        "definition",
+        "theorem",
+        "references"
+      ],
+      "components": [
+        "Definition",
+        "Theorem",
+        "Lemma",
+        "Corollary",
+        "Proposition",
+        "Proof",
+        "Example",
+        "Remark",
+        "Cite"
+      ]
+    }
+  },
+  "scripts": {
+    "dev": "kadal-deck dev -C preview",
+    "check": "kadal-deck check -C preview",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "@kadal/deck": "^0.4.1",
+    "react": "^19.2.0"
+  },
+  "devDependencies": {
+    "@kadal/deck": "workspace:*",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^6.0.2",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16"
+  }
+}