!xamix-element screenshot

!Lit component
!TypeScript
!License

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

$3

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

$3

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

$3

``bash
npm install @tlenexkoyotl/xamix-element
`

$3

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

Usage

$3

`html






text-input="ma-lin-zin _ i-tla'-tol"
root="node_modules/@tlenexkoyotl/xamix-element"
font-size="3.5">



`

$3

`html
text-input="i-ka _ i-nin _ a-mox-tli _ tik-pe-wal-ti-a'"
root="node_modules/@tlenexkoyotl/xamix-element"
vertical
font-size="2">

`

$3

`html
text-input="ma-lin-zin _ i-tla'-tol"
root="node_modules/@tlenexkoyotl/xamix-element"
links='[{"wordsIndexes": [0, 1], "href": "https://example.com"}]'>

`

$3

`html

`

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

$3

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:

$3


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

$3

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

$3

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

$3

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

$3

`
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

$3

`bash
npm run dev
`

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

$3

`bash
npm run build
`

Builds the component for production and generates TypeScript declaration files.

$3

`bash


Run tests

npm test

Run tests with UI

npm run test:ui
`

$3

`bash
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

$3

- Framework: Lit 3.2.0 (Web Components)
- Language: TypeScript 5.7
- Build Tool: Vite 6.0
- Testing: Vitest 2.1

$3

- 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

$3

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.

$3

- 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
- Technical Specifications
- Unicode Proposal Draft

---

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