feat: add 'highlight' component

This component shows a box with a title. Convenient for theorems and such.

Author: Tygo-van-den-Hurk

browser/css/tw-config.ts

@@ -1,5 +1,10 @@
 import type { SlydeHtmlDocumentCssProperties } from '#browser/css/types';
 
+/** Tells the config to force this to scale only using `--unit`. */
+const scaleWithUnit = Object.fromEntries(
+  Array.from({ length: 1000 }, (_ignore, amount) => [amount, `calc(${amount} * var(--unit))`])
+);
+
 /** The config for tailwind in the browser. */
 export const tailwindConfig = function tailwindConfig({
   background,
@@ -9,6 +14,12 @@ export const tailwindConfig = function tailwindConfig({
 }: SlydeHtmlDocumentCssProperties): { theme: Record<string, Record<string, unknown>> } {
   return {
     theme: {
+      /**
+       * Allow **only** the scale of `--unit` which is the unit of measurement in a slyde HTML document as it changes
+       * based on the size of the document. All other measurements don't.
+       */
+      borderWidth: scaleWithUnit,
+
       /**
        * Allow **only** these colors.
        */
@@ -37,9 +48,7 @@ export const tailwindConfig = function tailwindConfig({
        * Allow **only** the scale of `--unit` which is the unit of measurement in a slyde HTML document as it changes
        * based on the size of the document. All other measurements don't.
        */
-      spacing: Object.fromEntries(
-        Array.from({ length: 1000 }, (_ignore, amount) => [amount, `calc(${amount} * var(--unit))`])
-      ),
+      spacing: scaleWithUnit,
     },
   };
 };

lib/core/components/blocks/highlight.ts

@@ -0,0 +1,58 @@
+import { Component } from '#lib/core/components/class';
+
+/**
+ * A component that just shows a highlight block with a thicker left border.
+ *
+ * **Example**:
+ * ```Text
+ * ┌──────────────────────────────────────────────┐
+ * ┃ Some text to highlight                       │
+ * └──────────────────────────────────────────────┘
+ * ```
+ */
+@Component.register.using({ plugin: false })
+export class Highlight extends Component {
+  /** The color of the border around the box. */
+  readonly #borderColor: string = Component.utils.extract({
+    aliases: ['border-color', 'color'],
+    context: this,
+    fallback: 'var(--primary)',
+  });
+
+  /** The color of the border around the box. */
+  readonly #title: string | null = Component.utils.extract({
+    aliases: ['title', 'header'],
+    context: this,
+    fallback: null,
+  });
+
+  @Component.utils.children.require
+  // eslint-disable-next-line jsdoc/require-jsdoc
+  public render({ children }: Component.RenderArguments): string {
+    // eslint-disable-next-line no-inline-comments
+    let title = /*HTML*/ `
+      <h4 class="flex items-center gap-2 text-LG font-semibold" style="color:${this.#borderColor}">
+        ${this.#title}
+      </h4>
+    `;
+
+    if (this.#title === null) title = '';
+
+    const borderColor = `border-color:${this.#borderColor}`;
+    const borderWidth = `border-width:calc((1/6)*var(--unit));border-left-width:calc((3/6)*var(--unit));`;
+
+    // eslint-disable-next-line no-inline-comments
+    return /*HTML*/ `
+    <div class="p-1 mt-1" style="${borderColor};${borderWidth}">
+      ${title}
+      <div id="${this.id}-children-container">
+        ${children?.()}
+      </div>
+    </div>`;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/class-methods-use-this, jsdoc/require-jsdoc
+  public hierarchy(): ReturnType<Component.Interface['hierarchy']> {
+    return [Component.level.block, '+'];
+  }
+}

lib/core/components/blocks/index.ts

@@ -1,3 +1,4 @@
+export * from '#lib/core/components/blocks/highlight';
 export * from '#lib/core/components/blocks/image';
 export * from '#lib/core/components/blocks/point';
 export * from '#lib/core/components/blocks/qr-core';

test/lib/core/components/blocks/highlight.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'vitest';
+import { Component } from '#lib/core/components/class';
+import { Highlight } from '#lib/core/components/blocks/highlight';
+
+const Class = Highlight;
+
+describe(`class ${Class.name} implements Component`, () => {
+  test('Is registered as a component', () => {
+    expect(Component.retrieve(Class.name)).toBe(Class);
+  });
+
+  const construct = {
+    attributes: {},
+    focusMode: 'default' as const,
+    id: '',
+    level: Component.level.block,
+    path: '//',
+  } satisfies Component.ConstructorArguments;
+
+  test('Is creatable', () => {
+    expect(() => new Class({ ...construct })).not.toThrow();
+  });
+
+  const pattern = '<VERY-SPECIFIC-PATTERN>' as const;
+  const children = (() => pattern) as () => string;
+  const render = {} satisfies Component.RenderArguments;
+
+  test('renders with children', () => {
+    expect(() => new Class({ ...construct }).render({ ...render, children })).not.toThrow();
+  });
+
+  test('does not render without children', () => {
+    expect(() => new Class({ ...construct }).render({ ...render })).toThrow();
+  });
+
+  test('uses children within somewhere', () => {
+    expect(new Class({ ...construct }).render({ ...render, children })).toContain(pattern);
+  });
+});