fontist 2.1.2 → 2.1.4

data/docs/.vitepress/theme/index.ts

@@ -0,0 +1,12 @@
+import DefaultTheme from "vitepress/theme";
+import "./style.css";
+import WithinHero from "./components/WithinHero.vue";
+import HeroCodeBlock from "./components/HeroCodeBlock.vue";
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp({ app }) {
+    app.component("WithinHero", WithinHero);
+    app.component("HeroCodeBlock", HeroCodeBlock);
+  },
+};

data/docs/.vitepress/theme/style.css

@@ -0,0 +1,152 @@
+:root {
+  /* Brand Colors from Logo */
+  --fontist-rose: #bf4e6a;
+  --fontist-rose-light: #d4718a;
+  --fontist-dark: #4d4b54;
+  --fontist-gray: #676565;
+  --fontist-cream: #e1dfd2;
+  --fontist-beige: #bebbac;
+  --fontist-pale: #dddac8;
+
+  /* VitePress Theme Overrides - Light Mode */
+  --vp-c-brand-1: var(--fontist-rose);
+  --vp-c-brand-2: #a3435a;
+  --vp-c-brand-3: var(--fontist-dark);
+  --vp-c-brand-soft: rgba(191, 78, 106, 0.14);
+
+  /* Text Colors */
+  --vp-c-text-1: var(--fontist-dark);
+  --vp-c-text-2: var(--fontist-gray);
+  --vp-c-text-3: #8a8888;
+
+  /* Background Colors */
+  --vp-c-bg-soft: #f8f7f4;
+  --vp-c-bg-alt: #f2f1ed;
+  --vp-c-bg: #ffffff;
+
+  /* Hero */
+  --vp-home-hero-name-color: var(--fontist-rose);
+  --vp-home-hero-name-background: linear-gradient(
+    120deg,
+    var(--fontist-rose) 30%,
+    #d4718a
+  );
+
+  /* Buttons */
+  --vp-button-brand-border: var(--fontist-rose);
+  --vp-button-brand-text: #ffffff;
+  --vp-button-brand-bg: var(--fontist-rose);
+  --vp-button-brand-hover-border: #a3435a;
+  --vp-button-brand-hover-text: #ffffff;
+  --vp-button-brand-hover-bg: #a3435a;
+  --vp-button-brand-active-border: #8a3849;
+  --vp-button-brand-active-text: #ffffff;
+  --vp-button-brand-active-bg: #8a3849;
+
+  /* Sidebar */
+  --vp-sidebar-bg-color: var(--vp-c-bg-soft);
+
+  /* Nav */
+  --vp-nav-bg-color: var(--vp-c-bg);
+}
+
+/* Dark Mode */
+html.dark {
+  --vp-c-brand-1: var(--fontist-rose-light);
+  --vp-c-brand-2: var(--fontist-rose);
+  --vp-c-brand-3: #e1dfd2;
+  --vp-c-brand-soft: rgba(212, 113, 138, 0.14);
+
+  /* Text Colors - Dark Mode */
+  --vp-c-text-1: #e1dfd2;
+  --vp-c-text-2: #bebbac;
+  --vp-c-text-3: #8a8888;
+
+  /* Background Colors - Dark Mode */
+  --vp-c-bg: #1a1918;
+  --vp-c-bg-soft: #222120;
+  --vp-c-bg-alt: #2a2826;
+  --vp-c-bg-elv: #2a2826;
+
+  /* Hero - Dark Mode */
+  --vp-home-hero-name-background: linear-gradient(
+    120deg,
+    var(--fontist-rose-light) 30%,
+    #e08a9e
+  );
+
+  /* Buttons - Dark Mode */
+  --vp-button-brand-border: var(--fontist-rose-light);
+  --vp-button-brand-text: #1a1918;
+  --vp-button-brand-bg: var(--fontist-rose-light);
+  --vp-button-brand-hover-border: var(--fontist-rose);
+  --vp-button-brand-hover-text: #1a1918;
+  --vp-button-brand-hover-bg: var(--fontist-rose);
+  --vp-button-brand-active-border: #a3435a;
+  --vp-button-brand-active-text: #1a1918;
+  --vp-button-brand-active-bg: #a3435a;
+}
+
+/* Feature cards on home page - Light */
+.VPFeature .title {
+  color: var(--fontist-dark);
+}
+
+.VPFeature .details {
+  color: var(--fontist-gray);
+}
+
+.VPFeature:hover {
+  border-color: var(--fontist-rose);
+}
+
+/* Feature cards - Dark */
+html.dark .VPFeature .title {
+  color: var(--fontist-cream);
+}
+
+html.dark .VPFeature .details {
+  color: var(--fontist-beige);
+}
+
+/* Links */
+.vp-doc a {
+  color: var(--fontist-rose);
+}
+
+.vp-doc a:hover {
+  color: #a3435a;
+}
+
+html.dark .vp-doc a {
+  color: var(--fontist-rose-light);
+}
+
+html.dark .vp-doc a:hover {
+  color: var(--fontist-rose);
+}
+
+/* Footer */
+.VPFooter {
+  background-color: var(--vp-c-bg-soft);
+  border-top: 1px solid var(--fontist-pale);
+}
+
+html.dark .VPFooter {
+  border-top-color: #3a3836;
+}
+
+/* Code blocks - Light */
+.vp-doc [class*="language-"] {
+  background-color: var(--fontist-dark);
+}
+
+/* Code blocks - Dark */
+html.dark .vp-doc [class*="language-"] {
+  background-color: #0d0c0c;
+}
+
+/* Logo sizing */
+.VPNav .VPImage {
+  height: 39px;
+}

data/docs/api/errors.md

@@ -0,0 +1,211 @@
+---
+title: Fontist::Errors
+---
+
+# Fontist::Errors
+
+Fontist raises specific errors for various failure conditions. Understanding these errors helps you handle exceptions gracefully in your applications.
+
+## Overview
+
+All Fontist errors inherit from `Fontist::Errors::FontistError`, which is the base error class.
+
+## Error Classes
+
+### `Fontist::Errors::FontistError`
+
+The base error class for all Fontist errors.
+
+**Inherits from:** `StandardError`
+
+**Usage:**
+
+```ruby
+begin
+  Fontist::Font.find("NonExistent")
+rescue Fontist::Errors::FontistError => e
+  puts "Fontist error: #{e.message}"
+end
+```
+
+---
+
+### `Fontist::Errors::UnsupportedFontError`
+
+Raised when a requested font is not supported by Fontist.
+
+**When raised:**
+- Font name is not found in any formula
+- Font is not available for installation
+
+**Example:**
+
+```ruby
+begin
+  Fontist::Font.install("Unknown Font")
+rescue Fontist::Errors::UnsupportedFontError => e
+  puts "Font not supported: #{e.message}"
+end
+```
+
+---
+
+### `Fontist::Errors::MissingFontError`
+
+Raised when a required font is not installed on the system.
+
+**When raised:**
+- Font is supported but not installed
+- Font files are missing or corrupted
+
+**Example:**
+
+```ruby
+begin
+  Fontist::Font.find("Supported But Not Installed")
+rescue Fontist::Errors::MissingFontError => e
+  puts "Font needs to be installed: #{e.message}"
+end
+```
+
+---
+
+### `Fontist::Errors::LicensingError`
+
+Raised when there is an issue with font licensing.
+
+**When raised:**
+- Font requires license confirmation but none provided
+- License terms are not accepted
+
+**Example:**
+
+```ruby
+begin
+  Fontist::Font.install("Licensed Font", confirmation: "no")
+rescue Fontist::Errors::LicensingError => e
+  puts "License issue: #{e.message}"
+  # Prompt user for license acceptance
+  Fontist::Font.install("Licensed Font", confirmation: "yes")
+end
+```
+
+---
+
+### `Fontist::Errors::DownloadError`
+
+Raised when font download fails.
+
+**When raised:**
+- Network connection issues
+- Source URL is unavailable
+- Downloaded file is corrupted
+
+**Example:**
+
+```ruby
+begin
+  Fontist::Font.install("Some Font")
+rescue Fontist::Errors::DownloadError => e
+  puts "Download failed: #{e.message}"
+  # Retry or use alternative source
+end
+```
+
+---
+
+### `Fontist::Errors::InstallationError`
+
+Raised when font installation fails.
+
+**When raised:**
+- Insufficient disk space
+- Permission denied
+- Archive extraction fails
+
+**Example:**
+
+```ruby
+begin
+  Fontist::Font.install("Some Font")
+rescue Fontist::Errors::InstallationError => e
+  puts "Installation failed: #{e.message}"
+end
+```
+
+---
+
+### `Fontist::Errors::FormulaNotFoundError`
+
+Raised when a formula cannot be found.
+
+**When raised:**
+- Formula file is missing
+- Formula registry is corrupted
+
+**Example:**
+
+```ruby
+begin
+  Fontist::Formula.find("Unknown")
+rescue Fontist::Errors::FormulaNotFoundError => e
+  puts "Formula not found: #{e.message}"
+end
+```
+
+## Error Handling Best Practices
+
+### Catching Specific Errors
+
+```ruby
+begin
+  Fontist::Font.install("Calibri", confirmation: "yes")
+rescue Fontist::Errors::UnsupportedFontError
+  puts "This font is not supported"
+rescue Fontist::Errors::LicensingError
+  puts "License acceptance required"
+rescue Fontist::Errors::DownloadError
+  puts "Failed to download font"
+rescue Fontist::Errors::InstallationError
+  puts "Failed to install font"
+end
+```
+
+### Catching All Fontist Errors
+
+```ruby
+begin
+  Fontist::Font.install("Calibri", confirmation: "yes")
+rescue Fontist::Errors::FontistError => e
+  puts "Fontist operation failed: #{e.message}"
+end
+```
+
+### Checking Font Availability
+
+```ruby
+# Check if font is supported before installing
+begin
+  Fontist::Font.find("Open Sans")
+rescue Fontist::Errors::UnsupportedFontError
+  puts "Font not supported by Fontist"
+end
+```
+
+## Error Class Hierarchy
+
+```
+StandardError
+└── Fontist::Errors::FontistError
+    ├── UnsupportedFontError
+    ├── MissingFontError
+    ├── LicensingError
+    ├── DownloadError
+    ├── InstallationError
+    └── FormulaNotFoundError
+```
+
+## See Also
+
+- [Fontist::Font](/api/font) — Font installation and lookup
+- [Exit Codes](/cli/exit-codes) — CLI exit codes for errors

data/docs/api/font.md

@@ -0,0 +1,101 @@
+---
+title: Fontist::Font
+---
+
+# Fontist::Font
+
+The `Fontist::Font` is your go-to place to deal with any font using Fontist. This interface allows you to find a font or install a font.
+
+## Overview
+
+The Font class provides methods to:
+- Find fonts installed on your system
+- Install new fonts from supported sources
+- List all supported fonts
+
+It searches in operating system specific font directories and the fontist specific `~/.fontist` directory.
+
+## Class Methods
+
+### `.find(name)`
+
+Find a font in your system.
+
+**Parameters:**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `name` | String | The name of the font to find |
+
+**Returns:** `Array<String>` — Paths to the font files
+
+**Raises:**
+- `Fontist::Errors::UnsupportedFontError` — If the font is not supported
+- May trigger display of installation instructions for the specific font
+
+**Example:**
+
+```ruby
+paths = Fontist::Font.find("Calibri")
+# => ["/Users/user/.fontist/fonts/calibri.ttf"]
+```
+
+---
+
+### `.install(name, confirmation: "no")`
+
+Install any supported font.
+
+This interface first checks if you already have that font installed. If you do, it returns the paths. If you don't have the font but it is supported by Fontist, it will download the font, copy it to `~/.fontist` directory, and return the paths.
+
+**Parameters:**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `name` | String | The name of the font to install |
+| `confirmation` | String | License confirmation, use `"yes"` to accept license |
+
+**Returns:** `Array<String>` — Paths to the installed font files
+
+**Raises:**
+- `Fontist::Errors::UnsupportedFontError` — If the font is not supported
+- `Fontist::Errors::LicensingError` — If license requires confirmation
+
+**Example:**
+
+```ruby
+# Install with license acceptance
+paths = Fontist::Font.install("Open Sans", confirmation: "yes")
+# => ["/Users/user/.fontist/fonts/OpenSans-Regular.ttf"]
+
+# Install without license acceptance (may fail for licensed fonts)
+paths = Fontist::Font.install("Open Sans", confirmation: "no")
+```
+
+---
+
+### `.all`
+
+List all supported fonts.
+
+This might be useful if you want to know the name of the font or the available styles.
+
+**Parameters:** None
+
+**Returns:** `Array<Fontist::FontModel>` — Model objects representing supported fonts
+
+**Example:**
+
+```ruby
+fonts = Fontist::Font.all
+fonts.each do |font|
+  puts font.name
+  puts font.styles
+end
+```
+
+## See Also
+
+- [Fontist::Formula](/api/formula) — Access formula information for fonts
+- [Fontist::Manifest](/api/manifest) — Work with multiple fonts via manifest
+- [Fontist::Errors](/api/errors) — Error handling

data/docs/api/fontconfig.md

@@ -0,0 +1,82 @@
+---
+title: Fontist::Fontconfig
+---
+
+# Fontist::Fontconfig
+
+Fontist supports integration with Fontconfig via the Ruby interface.
+
+## Overview
+
+Fontconfig is a system for customizing and configuring font access. Fontist can update Fontconfig to detect fontist-managed fonts, allowing applications that use Fontconfig to find fonts installed by Fontist.
+
+## Class Methods
+
+### `.update`
+
+Update Fontconfig to let it detect fontist fonts.
+
+**Parameters:** None
+
+**Returns:** `Boolean` — Success status
+
+**Example:**
+
+```ruby
+Fontist::Fontconfig.update
+# => true
+```
+
+This makes fonts installed by Fontist visible to applications that use Fontconfig for font discovery.
+
+---
+
+### `.remove(force: false)`
+
+Disable detection of fontist fonts in Fontconfig.
+
+**Parameters:**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `force` | Boolean | If true, do not fail if no config exists |
+
+**Returns:** `Boolean` — Success status
+
+**Raises:** Error if config doesn't exist and `force` is `false`
+
+**Example:**
+
+```ruby
+# Remove fontconfig integration
+Fontist::Fontconfig.remove
+
+# Remove without failing if config doesn't exist
+Fontist::Fontconfig.remove(force: true)
+```
+
+## Typical Usage
+
+A common workflow when working with Fontconfig integration:
+
+```ruby
+# Install a font
+Fontist::Font.install("Open Sans", confirmation: "yes")
+
+# Update Fontconfig to detect the new font
+Fontist::Fontconfig.update
+
+# Now applications using Fontconfig can find the font
+```
+
+When you no longer need Fontist fonts to be visible:
+
+```ruby
+# Remove Fontconfig integration
+Fontist::Fontconfig.remove
+```
+
+## See Also
+
+- [Fontist::Font](/api/font) — Font installation
+- [Fontconfig CLI Reference](/cli/fontconfig) — Command-line interface

data/docs/api/formula.md

@@ -0,0 +1,103 @@
+---
+title: Fontist::Formula
+---
+
+# Fontist::Formula
+
+The `fontist` gem internally uses the `Fontist::Formula` interface to find a registered formula or fonts supported by any formula. Unless you need to do anything with formulas directly, you shouldn't need to work with this interface.
+
+## Overview
+
+Formulas contain the metadata and installation instructions for fonts. Each formula describes:
+- Font names and styles available
+- Download sources
+- License information
+- Extraction and installation steps
+
+## Class Methods
+
+### `.find(font_name)`
+
+Find a registered formula by font name. This interface takes a font name as an argument and looks through each of the registered formulas that offer this font installation.
+
+**Parameters:**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `font_name` | String | The name of the font to find a formula for |
+
+**Returns:** `Fontist::Formula` — The formula object for the font
+
+**Example:**
+
+```ruby
+formula = Fontist::Formula.find("Calibri")
+# => #<Fontist::Formula @name="calibri", ...>
+
+# Access formula properties
+puts formula.fonts
+puts formula.license
+```
+
+---
+
+### `.find_fonts(font_name)`
+
+List font styles supported by a formula. Normally, each font name can be associated with multiple styles or collections (e.g., `regular`, `bold`, `italic`).
+
+**Parameters:**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `font_name` | String | The name of the font to find styles for |
+
+**Returns:** `Array<Fontist::Font>` — List of font objects with their styles
+
+**Example:**
+
+```ruby
+fonts = Fontist::Formula.find_fonts("Calibri")
+fonts.each do |font|
+  puts "#{font.name} - #{font.style}"
+end
+# Calibri - Regular
+# Calibri - Bold
+# Calibri - Italic
+```
+
+---
+
+### `.all`
+
+List all registered font formulas. This might be useful if you want to know the name of the formula or what type of fonts can be installed using that formula.
+
+**Parameters:** None
+
+**Returns:** `Array<Fontist::Formula>` — Model objects representing all registered formulas
+
+**Example:**
+
+```ruby
+formulas = Fontist::Formula.all
+formulas.each do |formula|
+  puts formula.name
+  puts formula.fonts.map(&:name)
+end
+```
+
+## Formula Properties
+
+When you retrieve a formula object, you can access various properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | String | The formula identifier |
+| `fonts` | Array | List of fonts provided by this formula |
+| `license` | String | License information |
+| `homepage` | String | URL to font homepage |
+| `description` | String | Description of the font |
+
+## See Also
+
+- [Fontist::Font](/api/font) — Font installation and lookup
+- [Fontist::Manifest](/api/manifest) — Work with multiple fonts

data/docs/api/index.md

@@ -0,0 +1,49 @@
+---
+title: API Reference
+---
+
+# Fontist Ruby API
+
+Fontist can be used as a Ruby library for programmatic font management.
+
+## Overview
+
+The Fontist Ruby API provides interfaces for:
+- **Fontist::Font** — Find and install fonts
+- **Fontist::Formula** — Access formula information
+- **Fontist::Manifest** — Work with font manifests
+- **Fontist::Fontconfig** — Integrate with fontconfig
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'fontist'
+```
+
+Or install directly:
+
+```bash
+gem install fontist
+```
+
+## Quick Example
+
+```ruby
+require 'fontist'
+
+# Find a font
+paths = Fontist::Font.find("Open Sans")
+
+# Install a font
+paths = Fontist::Font.install("Open Sans", confirmation: "yes")
+```
+
+## Next Steps
+
+- [Fontist::Font](/api/font) — Font installation and lookup
+- [Fontist::Formula](/api/formula) — Formula information
+- [Fontist::Manifest](/api/manifest) — Manifest handling
+- [Fontist::Fontconfig](/api/fontconfig) — Fontconfig integration
+- [Fontist::Errors](/api/errors) — Error handling