@tlenexkoyotl/xamix-element

v2.0.3

Published

4 days ago

Lit web component that renders Nawatl-style text as SVG syllables

0High
0Medium
0Low

tlenexkoyotl

lit web-components nahuatl svg syllables

xamix-element screenshot

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)

Installation

As a Package Dependency

npm install @tlenexkoyotl/xamix-element

For Development

git clone https://gitlab.com/tlenexkoyotl/xamix-element.git
cd xamix-element
npm install

Usage

Basic Example

<!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

<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

<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

<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:

[
  {
    "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

npm run dev

Starts a development server with hot module replacement. Demo pages are available in the demo/ directory.

Building

npm run build

Builds the component for production and generates TypeScript declaration files.

Testing

# Run tests
npm test

# Run tests with UI
npm run test:ui

Preview Production Build

npm run preview

Project Structure

xamix-element/
├── src/
│   ├── 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

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

Version: 2.0.0
Author: Tlenexkoyotl
Status: Production-ready, actively maintained