blecsd 0.1.0

package/dist/widgets/fonts/index.d.ts

@@ -0,0 +1,211 @@
+import { z } from 'zod';
+
+/**
+ * Schema for a single character's bitmap data.
+ *
+ * @example
+ * ```typescript
+ * import { CharBitmapSchema } from 'blecsd/widgets/fonts';
+ *
+ * const result = CharBitmapSchema.safeParse({
+ *   width: 8,
+ *   height: 14,
+ *   bitmap: [
+ *     [0, 1, 1, 0],
+ *   ],
+ * });
+ * ```
+ */
+declare const CharBitmapSchema: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    bitmap: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>]>>>;
+}, z.core.$strip>;
+/**
+ * A single character's bitmap data.
+ *
+ * @example
+ * ```typescript
+ * import type { CharBitmap } from 'blecsd/widgets/fonts';
+ *
+ * const glyph: CharBitmap = {
+ *   width: 8,
+ *   height: 14,
+ *   bitmap: [],
+ * };
+ * ```
+ */
+type CharBitmap = z.infer<typeof CharBitmapSchema>;
+/**
+ * Schema for a complete bitmap font.
+ *
+ * @example
+ * ```typescript
+ * import { BitmapFontSchema } from 'blecsd/widgets/fonts';
+ *
+ * const font = BitmapFontSchema.parse({
+ *   name: 'Terminus',
+ *   size: 14,
+ *   weight: 'bold',
+ *   charWidth: 8,
+ *   charHeight: 14,
+ *   chars: {},
+ * });
+ * ```
+ */
+declare const BitmapFontSchema: z.ZodObject<{
+    name: z.ZodString;
+    size: z.ZodNumber;
+    weight: z.ZodEnum<{
+        bold: "bold";
+        normal: "normal";
+    }>;
+    charWidth: z.ZodNumber;
+    charHeight: z.ZodNumber;
+    chars: z.ZodRecord<z.ZodString, z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        bitmap: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>]>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * A complete bitmap font.
+ *
+ * @example
+ * ```typescript
+ * import type { BitmapFont } from 'blecsd/widgets/fonts';
+ *
+ * const font: BitmapFont = {
+ *   name: 'Terminus',
+ *   size: 14,
+ *   weight: 'normal',
+ *   charWidth: 8,
+ *   charHeight: 14,
+ *   chars: {},
+ * };
+ * ```
+ */
+type BitmapFont = z.infer<typeof BitmapFontSchema>;
+/**
+ * Built-in bitmap font names.
+ *
+ * @example
+ * ```typescript
+ * import type { FontName } from 'blecsd/widgets/fonts';
+ *
+ * const name: FontName = 'terminus-14-bold';
+ * ```
+ */
+type FontName = 'terminus-14-bold' | 'terminus-14-normal';
+/**
+ * Error thrown when a font name is not recognized.
+ *
+ * @example
+ * ```typescript
+ * import type { FontNotFoundError } from 'blecsd/widgets/fonts';
+ *
+ * const error = new Error('missing') as FontNotFoundError;
+ * error.name = 'FontNotFoundError';
+ * ```
+ */
+type FontNotFoundError = Error & {
+    name: 'FontNotFoundError';
+};
+/**
+ * Rendering options for bitmap characters.
+ *
+ * @example
+ * ```typescript
+ * import type { RenderCharOptions } from 'blecsd/widgets/fonts';
+ *
+ * const options: RenderCharOptions = { fillChar: '#', emptyChar: '.' };
+ * ```
+ */
+type RenderCharOptions = {
+    /** Character used to draw filled pixels */
+    fillChar?: string;
+    /** Character used to draw empty pixels */
+    emptyChar?: string;
+};
+/**
+ * Creates a font-not-found error for the given name.
+ *
+ * @param name - Font identifier that was requested
+ * @returns Error instance with a FontNotFoundError name
+ *
+ * @example
+ * ```typescript
+ * import { createFontNotFoundError } from 'blecsd/widgets/fonts';
+ *
+ * throw createFontNotFoundError('terminus-14-mono');
+ * ```
+ */
+declare const createFontNotFoundError: (name: string) => FontNotFoundError;
+/**
+ * Loads a built-in bitmap font by name.
+ *
+ * Font data is loaded lazily via dynamic import to avoid bundling ~3.2 MB
+ * of font JSON into the main entry point.
+ *
+ * @param name - Font identifier ('terminus-14-bold' | 'terminus-14-normal')
+ * @returns Promise resolving to the loaded bitmap font
+ * @throws {FontNotFoundError} If font name is not recognized
+ *
+ * @example
+ * ```typescript
+ * import { loadFont } from 'blecsd/widgets/fonts';
+ *
+ * const font = await loadFont('terminus-14-bold');
+ * console.log(font.charWidth, font.charHeight); // 8, 14
+ * ```
+ */
+declare const loadFont: (name: FontName) => Promise<BitmapFont>;
+/**
+ * Returns a cached font if previously loaded, or undefined.
+ * Use this for synchronous access after an initial `loadFont` call.
+ *
+ * @param name - Font identifier
+ * @returns The cached font, or undefined if not yet loaded
+ *
+ * @example
+ * ```typescript
+ * import { loadFont, getCachedFont } from 'blecsd/widgets/fonts';
+ *
+ * await loadFont('terminus-14-bold');
+ * const font = getCachedFont('terminus-14-bold'); // synchronous
+ * ```
+ */
+declare const getCachedFont: (name: FontName) => BitmapFont | undefined;
+/**
+ * Gets the bitmap data for a specific character.
+ *
+ * @param font - The bitmap font to use
+ * @param char - Single character to look up
+ * @returns Bitmap data for the character, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const bitmap = getCharBitmap(font, 'A');
+ * if (bitmap) {
+ *   console.log(bitmap.width, bitmap.height);
+ * }
+ * ```
+ */
+declare const getCharBitmap: (font: BitmapFont, char: string) => CharBitmap | undefined;
+/**
+ * Renders a character to an array of strings using block characters.
+ *
+ * @param font - The bitmap font to use
+ * @param char - Character to render
+ * @param options - Rendering options
+ * @returns Array of strings representing the rendered character
+ *
+ * @example
+ * ```typescript
+ * const lines = renderChar(font, 'A', { fillChar: '█', emptyChar: ' ' });
+ * lines.forEach(line => console.log(line));
+ * ```
+ */
+declare const renderChar: (font: BitmapFont, char: string, options?: RenderCharOptions) => readonly string[];
+
+export { type BitmapFont, BitmapFontSchema, type CharBitmap, CharBitmapSchema, type FontName, type FontNotFoundError, type RenderCharOptions, createFontNotFoundError, getCachedFont, getCharBitmap, loadFont, renderChar };

package/dist/widgets/fonts/index.js

@@ -0,0 +1 @@
+export{b as BitmapFontSchema,a as CharBitmapSchema,c as createFontNotFoundError,e as getCachedFont,f as getCharBitmap,d as loadFont,g as renderChar}from'../../chunk-DNRXW56C.js';import'../../chunk-5PELJRUQ.js';