npm - @tlenexkoyotl/xamix-element - Versions diffs - 1.0.2 → 2.0.1 - Mend

@tlenexkoyotl/xamix-element 1.0.2 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md +268 -29
package/dist/types.d.ts +50 -0
package/dist/types.d.ts.map +1 -0
package/dist/xamix-element-styles.d.ts +3 -0
package/dist/xamix-element-styles.d.ts.map +1 -0
package/dist/xamix-element.d.ts +60 -0
package/dist/xamix-element.d.ts.map +1 -0
package/dist/xamix-element.js +343 -243
package/package.json +12 -5

package/README.md CHANGED Viewed

@@ -2,38 +2,217 @@
 # <xamix-element>
 ![Lit component](https://img.shields.io/badge/lit-component-blue.svg)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
-> A Lit Web Component built with Vite and TypeScript
+> A Lit Web Component for rendering the Xamix writing system in web applications
+## About Xamix
+**Xamix** is a modern syllabic writing system developed starting in 2019 for writing Nahuatl. Unlike traditional Latin-based orthographies, Xamix uses a unique glyph for each syllable, providing a visually distinct as well as phonetically and grammatically accurate representation of the language.
+### Key Features of Xamix
+- **7,770+ unique syllable glyphs** - Each syllable has its own distinct character
+- **Syllabic structure** - Represents complete syllables (CV, CCV, CVV, etc.)
+- **Dual rendering modes** - Supports both horizontal (right-to-left) and vertical (top-to-bottom) text layouts
+- **Visual distinctiveness** - Designed to be visually distinct from Latin characters
+- **Phonetic accuracy** - Accurately represents syllable boundaries and phonetic distinctions
+## About This Component
+`xamix-element` is a production-ready Lit Web Component that renders Xamix text by dynamically loading and displaying SVG syllable glyphs. It's designed for use in web applications, educational software, digital publications, and language learning resources.
+### Component Features
+- ✅ **Dynamic SVG loading** - Efficiently fetches and caches SVG syllable glyphs
+- ✅ **Horizontal and vertical layouts** - Supports both text directions
+- ✅ **Customizable styling** - CSS variables for colors, spacing, and layout
+- ✅ **Link support** - Convert specific words into clickable links
+- ✅ **Responsive sizing** - Flexible font size and unit system (vw, vh, em, etc.)
+- ✅ **Bold variant** - Supports both regular and bold glyph styles
+- ✅ **TypeScript** - Fully typed with TypeScript definitions
+- ✅ **Well tested** - Comprehensive test suite with Vitest
+- ✅ **Performance optimized** - SVG caching, batch fetching, and abort controllers
 ## Prerequisites
 - **Node.js**: 20.19+ or 22.12+ (latest LTS recommended)
 - **npm**: Latest version (update with `npm install -g npm@latest`)
-## Install
+## Installation
+### As a Package Dependency
 ```bash
 npm install @tlenexkoyotl/xamix-element
 ```
-For project development (clone + deps):
+### For Development
 ```bash
+git clone https://gitlab.com/tlenexkoyotl/xamix-element.git
+cd xamix-element
 npm install
 ```
+## Usage
+### Basic Example
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script type="module">
+    import '@tlenexkoyotl/xamix-element';
+  </script>
+</head>
+<body>
+  <xamix-element
+    text-input="ma-lin-zin _ i-tla'-tol"
+    root="node_modules/@tlenexkoyotl/xamix-element"
+    font-size="3.5">
+  </xamix-element>
+</body>
+</html>
+```
+### Vertical Text Layout
+```html
+<xamix-element
+  text-input="i-ka _ i-nin _ a-mox-tli _ tik-pe-wal-ti-a'"
+  root="node_modules/@tlenexkoyotl/xamix-element"
+  vertical
+  font-size="2">
+</xamix-element>
+```
+### With Links
+```html
+<xamix-element
+  text-input="ma-lin-zin _ i-tla'-tol"
+  root="node_modules/@tlenexkoyotl/xamix-element"
+  links='[{"wordsIndexes": [0, 1], "href": "https://example.com"}]'>
+</xamix-element>
+```
+### Styling with CSS Variables
+```html
+<style>
+  xamix-element {
+    --xamix-text-color: #333;
+    --xamix-link-color: #0066cc;
+    --xamix-vertical-writing-mode: vertical-rl;
+  }
+</style>
+```
+## Component Attributes
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `text-input` | string | `''` | Syllable-based text input (hyphen-separated syllables, space-separated words) |
+| `root` | string | `'.'` | Path to the package directory containing the `data/` folder |
+| `font-size` | number | `3` | Font size in the specified unit |
+| `unit` | string | `'vw'` | CSS unit for sizing (`vw`, `vh`, `em`, `px`, etc.) |
+| `vertical` | boolean | `false` | Enable vertical text layout (top-to-bottom) |
+| `bold` | boolean | `false` | Use bold variant glyphs |
+| `adaptable` | boolean | `false` | Automatically switch between `vw` and `vh` based on aspect ratio |
+| `links` | string | `''` | JSON array of link configurations (see below) |
+### Link Configuration
+The `links` attribute accepts a JSON array of link objects:
+```json
+[
+  {
+    "wordsIndexes": [0, 1, 2],
+    "href": "https://example.com"
+  }
+]
+```
+- `wordsIndexes`: Array of word indices (0-based) to convert into links
+- `href`: URL for the link
+## CSS Custom Properties
+The component supports extensive CSS customization via CSS variables:
+### Text Styling
+- `--xamix-text-color`: Text color (default: `currentColor`)
+- `--xamix-text-stroke`: Stroke color (default: `transparent`)
+- `--xamix-text-stroke-width`: Stroke width (default: `0`)
+- `--xamix-text-background-color`: Background color for text container
+- `--xamix-text-align`: Text alignment (default: `justify`)
+- `--xamix-text-line-height`: Line height (default: `0`)
+### Link Styling
+- `--xamix-link-color`: Default link color
+- `--xamix-link-unvisited-color`: Unvisited link color
+- `--xamix-link-visited-color`: Visited link color
+- `--xamix-link-hover-color`: Hover state color
+- `--xamix-link-active-color`: Active state color
+- `--xamix-link-focused-color`: Focus state color
+### Layout
+- `--xamix-horizontal-direction`: Horizontal text direction (default: `rtl`)
+- `--xamix-vertical-direction`: Vertical text direction (default: `ltr`)
+- `--xamix-vertical-writing-mode`: Vertical writing mode (default: `vertical-rl`)
+- `--xamix-columns-direction`: Column direction (default: `ltr`)
+- `--xamix-word-display`: Word display type (default: `inline-block`)
+- `--xamix-syllable-display`: Syllable display type (default: `inline-block`)
+### Spacing
+- `--xamix-vertical-syllable-spacing`: Spacing between syllables in vertical mode (default: `-0.15em`)
+## Text Input Format
+The component uses a syllable-based input format:
+- **Syllables** are separated by hyphens: `ma-lin-zin`
+- **Words** are separated by spaces: `ma-lin-zin _ i-tla'-tol`
+- **Special markers** use underscores: `tlamilistli`, `zikoalistli1`, `nimanilistli`
+### Examples
+```
+ma-lin-zin _ i-tla'-tol
+→ "Malinzin's words"
+re-fukh-yo _ na-va _ na-va
+→ "Refugio Nava Nava"
+i-ka _ i-nin _ a-mox-tli _ tik-pe-wal-ti-a'
+→ "And in this book we present"
+```
 ## Development
+### Development Server
 ```bash
-# Start development server
 npm run dev
+```
+Starts a development server with hot module replacement. Demo pages are available in the `demo/` directory.
-# Build for production
+### Building
+```bash
 npm run build
+```
-# Preview production build
-npm run preview
+Builds the component for production and generates TypeScript declaration files.
+### Testing
+```bash
 # Run tests
 npm test
@@ -41,41 +220,101 @@ npm test
 npm run test:ui
 ```
-## Usage
-```html
-<script type="module">
-  import '@tlenexkoyotl/xamix-element';
-</script>
+### Preview Production Build
-<xamix-element
-  text-input="ma-lin-zin _ i-tla'-tol"
-  root="node_modules/@tlenexkoyotl/xamix-element"
-  vertical
-  font-size="3.5">
-</xamix-element>
+```bash
+npm run preview
 ```
-Set `root` to the path where the package is installed (e.g. `node_modules/@tlenexkoyotl/xamix-element`) so the component can load SVG data from the `data/` folder.
 ## Project Structure
 ```
 xamix-element/
 ├── src/
-│   ├── xamix-element.ts      # Main component
-│   └── xamix-element-styles.ts # Component styles
-├── demo/                      # Demo pages
-├── test/                      # Test files
-├── data/                      # SVG assets
-├── dist/                       # Build output
-└── vite.config.ts             # Vite configuration
+│   ├── xamix-element.ts          # Main component implementation
+│   ├── xamix-element-styles.ts    # Component styles
+│   └── types.ts                   # TypeScript type definitions
+├── data/
+│   ├── regular/                   # Regular variant SVG glyphs (7,770+ files)
+│   └── bold/                      # Bold variant SVG glyphs
+├── demo/                          # Demo pages
+│   ├── index.html                 # Main demo
+│   ├── index2.html                # Numbers demo
+│   ├── index3.html                # Vertical layout demo
+│   └── index4.html                # Horizontal layout demo
+├── test/                          # Test files
+│   └── xamix-element.spec.ts      # Component tests
+├── scripts/                       # Utility scripts
+│   ├── generate-unicode-mapping.ts
+│   ├── generate-proposal-materials.ts
+│   └── ...
+├── proposal/                      # Unicode proposal materials
+├── dist/                          # Build output
+└── vite.config.ts                 # Vite configuration
 ```
+## Technical Details
+### Architecture
+- **Framework**: Lit 3.2.0 (Web Components)
+- **Language**: TypeScript 5.7
+- **Build Tool**: Vite 6.0
+- **Testing**: Vitest 2.1
+### Performance Features
+- **SVG Caching**: Static cache with size limit (1000 entries) to avoid redundant fetches
+- **Batch Fetching**: Fetches SVGs in batches of 5 with 50ms delays
+- **Abort Controllers**: Cancels ongoing fetches when text changes to prevent race conditions
+- **Lazy Loading**: Only loads SVGs for syllables actually used in the text
+### Browser Support
+Works in all modern browsers that support:
+- Web Components (Custom Elements v1)
+- ES Modules
+- Fetch API
+- SVG rendering
+## Unicode Proposal
+This project is part of an ongoing effort to encode the Xamix writing system in Unicode. Materials for the Unicode proposal are available in the `proposal/` directory.
+For more information about the Unicode proposal process, see:
+- `proposal/README.md` - Proposal overview
+- `proposal/PROPOSAL-TIMELINE.md` - Timeline and process
+- `scripts/UNICODE-PROPOSAL-PROCESS.md` - Detailed process information
 ## Contributing
-PRs accepted. Please contribute!
+Contributions are welcome! Please feel free to submit pull requests or open issues.
+### Areas for Contribution
+- Additional demo examples
+- Performance optimizations
+- Documentation improvements
+- Test coverage expansion
+- Accessibility enhancements
 ## License
 MIT
+## Repository
+- **GitLab**: https://gitlab.com/tlenexkoyotl/xamix-element
+- **npm**: https://www.npmjs.com/package/@tlenexkoyotl/xamix-element
+## Related Resources
+- [Xamix Writing System Documentation](./proposal/documentation/writing-system-description.md)
+- [Technical Specifications](./proposal/documentation/technical-specifications.md)
+- [Unicode Proposal Draft](./proposal/proposal-draft.md)
+---
+**Version**: 2.0.0
+**Author**: Tlenexkoyotl
+**Status**: Production-ready, actively maintained

package/dist/types.d.ts ADDED Viewed

@@ -0,0 +1,50 @@
+/**
+ * Type definitions for xamix-element
+ */
+/**
+ * Processing stage of the component
+ */
+export declare enum ProcessingStage {
+    ON_CONSTRUCT = "on-construct",
+    WORDS_LOADING = "words-loading",
+    WORDS_LOADED = "words-loaded",
+    WORDS_RESIZING = "words-resizing",
+    WORDS_RESIZED = "words-resized"
+}
+/**
+ * CSS unit types
+ */
+export type CSSUnit = 'vw' | 'vh' | 'px' | 'em' | 'rem';
+/**
+ * Link configuration for word linking
+ */
+export interface Link {
+    readonly wordsIndexes: readonly number[];
+    readonly href: string;
+}
+/**
+ * Parsed word with components and output
+ */
+export interface ParsedWord {
+    readonly word: string;
+    readonly components: readonly string[];
+    textOutput?: (HTMLElement | SVGElement)[];
+    content?: HTMLElement | null;
+}
+/**
+ * Unique character/syllable with optional file content
+ */
+export interface UniqueCharacter {
+    readonly name: string;
+    file?: Promise<string> | string;
+}
+/**
+ * Bounding box from SVG getBBox()
+ */
+export interface SVGBoundingBox {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,oBAAY,eAAe;IACzB,YAAY,iBAAiB;IAC7B,aAAa,kBAAkB;IAC/B,YAAY,iBAAiB;IAC7B,cAAc,mBAAmB;IACjC,aAAa,kBAAkB;CAChC;AAED;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,UAAU,CAAC,EAAE,CAAC,WAAW,GAAG,UAAU,CAAC,EAAE,CAAC;IAC1C,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB"}

package/dist/xamix-element-styles.d.ts ADDED Viewed

@@ -0,0 +1,3 @@
+declare const _default: import("lit").CSSResult;
+export default _default;
+//# sourceMappingURL=xamix-element-styles.d.ts.map

package/dist/xamix-element-styles.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"xamix-element-styles.d.ts","sourceRoot":"","sources":["../src/xamix-element-styles.ts"],"names":[],"mappings":";AAEA,wBAuGE"}

package/dist/xamix-element.d.ts ADDED Viewed

@@ -0,0 +1,60 @@
+import { LitElement, PropertyValues } from 'lit';
+import type { Link, ParsedWord, UniqueCharacter, CSSUnit } from './types.js';
+import { ProcessingStage } from './types.js';
+export declare class XamixElement extends LitElement {
+    fontSize: number;
+    root: string;
+    vertical: boolean;
+    adaptable: boolean;
+    bold: boolean;
+    unit: CSSUnit;
+    textInput: string;
+    parsedText: ParsedWord[];
+    textOutput: (HTMLElement | SVGElement)[];
+    links: Link[];
+    stage: ProcessingStage;
+    private static readonly svgCache;
+    private static readonly MAX_CACHE_SIZE;
+    private uniqueCharacters;
+    private lastProcessedTextInput;
+    private abortController;
+    constructor();
+    private setViewBox;
+    private formViewbox;
+    private formHorizontalViewbox;
+    private formVerticalViewbox;
+    private getAspectRatio;
+    private getUnit;
+    private horizontalResize;
+    private verticalResize;
+    private resizeSvg;
+    private appendSvg;
+    private fetchSvg;
+    private parseText;
+    private setUniqueCharactersContent;
+    private fetchSyllables;
+    private useWordAsLink;
+    private setWordContent;
+    private formWordOutput;
+    private finishTextOutput;
+    private formTextOutput;
+    private convertInput;
+    private dispatchStageEvent;
+    private dispatchCurrentStage;
+    private resizeSvgs;
+    static styles: import("lit").CSSResult;
+    firstUpdated(changedProperties: PropertyValues): void;
+    willUpdate(changedProperties: PropertyValues): void;
+    render(): import("lit-html").TemplateResult<1>;
+    private insertTextOutput;
+    updated(changedProperties: PropertyValues): void;
+    disconnectedCallback(): void;
+}
+export type { Link, ParsedWord, UniqueCharacter, CSSUnit };
+export { ProcessingStage };
+declare global {
+    interface HTMLElementTagNameMap {
+        'xamix-element': XamixElement;
+    }
+}
+//# sourceMappingURL=xamix-element.d.ts.map

package/dist/xamix-element.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"xamix-element.d.ts","sourceRoot":"","sources":["../src/xamix-element.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,UAAU,EAAE,cAAc,EAAE,MAAM,KAAK,CAAC;AAGvD,OAAO,KAAK,EACV,IAAI,EACJ,UAAU,EACV,eAAe,EACf,OAAO,EAER,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAW7C,qBACa,YAAa,SAAQ,UAAU;IAE1C,QAAQ,SAAqB;IAG7B,IAAI,SAAgB;IAGpB,QAAQ,UAAS;IAGjB,SAAS,UAAS;IAGlB,IAAI,UAAS;IAGb,IAAI,EAAE,OAAO,CAAgB;IAG7B,SAAS,EAAE,MAAM,CAAM;IAGvB,UAAU,EAAE,UAAU,EAAE,CAAM;IAG9B,UAAU,EAAE,CAAC,WAAW,GAAG,UAAU,CAAC,EAAE,CAAM;IAqB9C,KAAK,EAAE,IAAI,EAAE,CAAM;IAgBnB,KAAK,EAAE,eAAe,CAAgC;IAEtD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IACtE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAQ;IAE9C,OAAO,CAAC,gBAAgB,CAAyB;IACjD,OAAO,CAAC,sBAAsB,CAAc;IAC5C,OAAO,CAAC,eAAe,CAAgC;;IAOvD,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,qBAAqB;IAqB7B,OAAO,CAAC,mBAAmB;IAe3B,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,cAAc;IAmBtB,OAAO,CAAC,SAAS;IA4BjB,OAAO,CAAC,SAAS;IAsDjB,OAAO,CAAC,QAAQ;IAoChB,OAAO,CAAC,SAAS;IAkBjB,OAAO,CAAC,0BAA0B;IAUlC,OAAO,CAAC,cAAc;IA+DtB,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,cAAc;IAkBtB,OAAO,CAAC,cAAc;IA0CtB,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,YAAY;IAgEpB,OAAO,CAAC,kBAAkB;IAQ1B,OAAO,CAAC,oBAAoB;IAI5B,OAAO,CAAC,UAAU;IAelB,MAAM,CAAC,MAAM,0BAAS;IAEtB,YAAY,CAAC,iBAAiB,EAAE,cAAc,GAAG,IAAI;IAiBrD,UAAU,CAAC,iBAAiB,EAAE,cAAc,GAAG,IAAI;IAwBnD,MAAM;IAkBN,OAAO,CAAC,gBAAgB;IA+CxB,OAAO,CAAC,iBAAiB,EAAE,cAAc,GAAG,IAAI;IA4BhD,oBAAoB,IAAI,IAAI;CAS7B;AAGD,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,eAAe,EAAE,YAAY,CAAC;KAC/B;CACF"}