liquidbook 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6c2c697f9bb5b094c752a0798ef24b5bf0265f60c5ed490abe4b9ad2abbb2d60
+  data.tar.gz: dda835eaec1bef74610452dfe1596a1b517122ca9e66a852592aa5ca79a43700
+SHA512:
+  metadata.gz: a5ff5a395bdf717724ebec570cb4fb8ff039d4cd9940dbb2df6320e402e0ae18511d5ec2d1ebeca9f598b73f0b81cc96977bae7bcb996117fc0e07e8380d10ff
+  data.tar.gz: 731b75e5e253632d37d58033f49d12c4ef74820397212750174bc2e66b9d01c8ad980be48108197effefab90ec4009c6d57becd4b494793f17f0471659665efa

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sena Murakami
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,83 @@
+# Liquidbook
+
+[![CI](https://github.com/sena-m09/liquidbook/actions/workflows/test.yml/badge.svg)](https://github.com/sena-m09/liquidbook/actions/workflows/test.yml)
+
+A Storybook-like local preview server for Shopify Liquid templates. Browse and preview your sections and snippets in the browser instantly.
+
+## Features
+
+- Auto-discovers `.liquid` files in `sections/` and `snippets/`
+- Generates default setting values from `{% schema %}` blocks
+- Supports Shopify-compatible filters and tags (`section`, `render`)
+- Load external CSS/JS via `.liquid-preview/config.yml`
+- File watching with live reload
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "liquidbook"
+```
+
+Or install directly:
+
+```bash
+gem install liquidbook
+```
+
+## Usage
+
+### Start the preview server
+
+Run from your Shopify theme root:
+
+```bash
+liquidbook server
+```
+
+Open `http://127.0.0.1:4567` in your browser to see a list of sections and snippets with live previews.
+
+#### Options
+
+| Option | Short | Default | Description |
+|---|---|---|---|
+| `--port` | `-p` | `4567` | Port number |
+| `--host` | `-H` | `127.0.0.1` | Host to bind |
+| `--root` | `-r` | `.` | Theme root directory |
+
+### Render a single template
+
+```bash
+liquidbook render sections/header.liquid
+```
+
+Outputs the rendered HTML to stdout.
+
+## Configuration
+
+Create `.liquid-preview/config.yml` in your theme root to load external assets into the preview:
+
+```yaml
+head:
+  - <script src="https://cdn.tailwindcss.com"></script>
+  - ../src/styles/main.css
+  - ./src/components.js
+
+port: 4567
+host: 127.0.0.1
+```
+
+`head` entries accept raw HTML tags or file paths. File paths are resolved relative to the theme root.
+
+## Development
+
+```bash
+git clone https://github.com/sena-m09/liquidbook.git
+cd liquidbook
+bin/setup
+```
+
+## License
+
+[MIT License](https://opensource.org/licenses/MIT)

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/docs/README.ja.md

@@ -0,0 +1,81 @@
+# Liquidbook
+
+Shopify Liquid テンプレートのローカルプレビューサーバー。Storybook のように、sections や snippets をブラウザ上で即座に確認できます。
+
+## 特徴
+
+- `sections/` や `snippets/` 内の `.liquid` ファイルを自動検出してプレビュー
+- `{% schema %}` ブロックからデフォルト設定値を自動生成
+- Shopify 互換フィルター・タグ (`section`, `render`) をサポート
+- `.liquid-preview/config.yml` で外部 CSS/JS の読み込みに対応
+- ファイル変更の自動検知（live reload）
+
+## インストール
+
+Gemfile に追加:
+
+```ruby
+gem "liquidbook"
+```
+
+または直接インストール:
+
+```bash
+gem install liquidbook
+```
+
+## 使い方
+
+### プレビューサーバーの起動
+
+Shopify テーマのルートディレクトリで実行:
+
+```bash
+liquidbook server
+```
+
+ブラウザで `http://127.0.0.1:4567` を開くと、sections / snippets の一覧とプレビューが表示されます。
+
+#### オプション
+
+| オプション | 短縮 | デフォルト | 説明 |
+|---|---|---|---|
+| `--port` | `-p` | `4567` | ポート番号 |
+| `--host` | `-H` | `127.0.0.1` | バインドするホスト |
+| `--root` | `-r` | `.` | テーマのルートディレクトリ |
+
+### 単一テンプレートのレンダリング
+
+```bash
+liquidbook render sections/header.liquid
+```
+
+標準出力に HTML が出力されます。
+
+## 設定
+
+テーマルートに `.liquid-preview/config.yml` を作成すると、プレビューに外部アセットを読み込めます。
+
+```yaml
+head:
+  - <script src="https://cdn.tailwindcss.com"></script>
+  - ../src/styles/main.css
+  - ./src/components.js
+
+port: 4567
+host: 127.0.0.1
+```
+
+`head` エントリには生の HTML タグまたはファイルパスを指定できます。ファイルパスはテーマルートからの相対パスで解決されます。
+
+## 開発
+
+```bash
+git clone https://github.com/sena-m09/liquidbook.git
+cd liquidbook
+bin/setup
+```
+
+## ライセンス
+
+[MIT License](https://opensource.org/licenses/MIT)

data/exe/liquidbook

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/liquidbook"
+require_relative "../lib/liquidbook/cli"
+
+Liquidbook::CLI.start(ARGV)

data/fixtures/default_mocks.yml

@@ -0,0 +1,88 @@
+shop:
+  name: "Preview Shop"
+  url: "https://preview-shop.myshopify.com"
+  currency: "JPY"
+  money_format: "¥{{amount}}"
+
+product:
+  title: "サンプル商品"
+  handle: "sample-product"
+  description: "<p>これはプレビュー用のサンプル商品です。</p>"
+  price: 1980
+  compare_at_price: 2980
+  available: true
+  type: "サンプル"
+  vendor: "Preview Vendor"
+  featured_image:
+    src: "https://placehold.co/600x600/EEE/31343C?text=Product"
+    alt: "サンプル商品画像"
+    width: 600
+    height: 600
+  images:
+    - src: "https://placehold.co/600x600/EEE/31343C?text=Image+1"
+      alt: "商品画像 1"
+    - src: "https://placehold.co/600x600/EEE/31343C?text=Image+2"
+      alt: "商品画像 2"
+  variants:
+    - title: "デフォルト"
+      price: 1980
+      available: true
+      sku: "SAMPLE-001"
+  tags:
+    - "sample"
+    - "preview"
+
+collection:
+  title: "サンプルコレクション"
+  handle: "sample-collection"
+  description: "プレビュー用コレクション"
+  products_count: 12
+  products:
+    - title: "商品 1"
+      handle: "product-1"
+      price: 1980
+      featured_image:
+        src: "https://placehold.co/400x400/EEE/31343C?text=1"
+    - title: "商品 2"
+      handle: "product-2"
+      price: 2980
+      featured_image:
+        src: "https://placehold.co/400x400/EEE/31343C?text=2"
+    - title: "商品 3"
+      handle: "product-3"
+      price: 3980
+      featured_image:
+        src: "https://placehold.co/400x400/EEE/31343C?text=3"
+
+cart:
+  item_count: 2
+  total_price: 4960
+  items:
+    - title: "商品 1"
+      quantity: 1
+      price: 1980
+    - title: "商品 2"
+      quantity: 1
+      price: 2980
+
+page:
+  title: "サンプルページ"
+  handle: "sample-page"
+  content: "<p>プレビュー用のページコンテンツです。</p>"
+
+customer:
+  first_name: "太郎"
+  last_name: "テスト"
+  email: "test@example.com"
+
+request:
+  locale:
+    iso_code: "ja"
+    name: "Japanese"
+  host: "localhost:4567"
+
+settings:
+  type_header_font:
+    family: "sans-serif"
+  type_body_font:
+    family: "sans-serif"

data/lib/liquidbook/cli.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "thor"
+require "fileutils"
+
+module Liquidbook
+  class CLI < Thor
+    default_command :server
+
+    desc "server", "Start the preview server"
+    option :port, type: :numeric, default: 4567, aliases: "-p", desc: "Port number"
+    option :host, type: :string, default: "127.0.0.1", aliases: "-H", desc: "Host to bind"
+    option :root, type: :string, default: ".", aliases: "-r", desc: "Theme root directory"
+    def server
+      theme_root = File.expand_path(options[:root])
+      Liquidbook.root = theme_root
+
+      pid_manager = PidManager.new(theme_root: theme_root)
+      result = pid_manager.ensure_can_start!
+      warn "Warning: Removed stale PID file." if result == :stale_pid_cleaned
+
+      puts "Liquidbook v#{VERSION}"
+      puts "Theme root: #{theme_root}"
+      puts "Server: http://#{options[:host]}:#{options[:port]}"
+      puts ""
+
+      sections = Dir.glob(File.join(theme_root, "sections", "*.liquid")).size
+      snippets = Dir.glob(File.join(theme_root, "snippets", "*.liquid")).size
+      puts "Found #{sections} sections, #{snippets} snippets"
+      puts ""
+
+      pid_manager.write_pid
+      at_exit { pid_manager.remove_pid }
+
+      Server::App.set :port, options[:port]
+      Server::App.set :bind, options[:host]
+      Server::App.run!
+    end
+
+    desc "stop", "Stop the running preview server"
+    option :root, type: :string, default: ".", aliases: "-r", desc: "Theme root directory"
+    def stop
+      theme_root = File.expand_path(options[:root])
+      pid_manager = PidManager.new(theme_root: theme_root)
+
+      case pid_manager.stop!
+      when :stopped
+        puts "Server stopped."
+      when :not_running
+        puts "Server is not running."
+      when :stale_pid_cleaned
+        puts "Server is not running (removed stale PID file)."
+      end
+    rescue Liquidbook::Error => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+
+    desc "render TEMPLATE", "Render a single template to stdout"
+    option :root, type: :string, default: ".", aliases: "-r", desc: "Theme root directory"
+    def render(template)
+      theme_root = File.expand_path(options[:root])
+      Liquidbook.root = theme_root
+
+      renderer = ThemeRenderer.new(theme_root: theme_root)
+
+      if template.start_with?("sections/") || template.start_with?("snippets/")
+        dir, name = template.split("/", 2)
+        name = name.sub(/\.liquid$/, "")
+        html = dir == "sections" ? renderer.render_section(name) : renderer.render_snippet(name)
+      else
+        html = renderer.render_section(template.sub(/\.liquid$/, ""))
+      end
+
+      puts html
+    rescue Liquidbook::Error => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+
+    desc "version", "Show version"
+    def version
+      puts "liquidbook #{VERSION}"
+    end
+  end
+end

data/lib/liquidbook/config.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Liquidbook
+  # Loads .liquid-preview/config.yml from the theme root
+  #
+  # head entries can be:
+  #   - Raw HTML:  <script src="https://cdn.tailwindcss.com"></script>
+  #   - File path: ../src-lit/styles/main.css
+  #   - File path: ./src/components.js
+  #
+  # File paths are resolved relative to the theme root and served via /__imports__/
+  class Config
+    DEFAULT_CONFIG = {
+      "head" => [],
+      "port" => 4567,
+      "host" => "127.0.0.1"
+    }.freeze
+
+    IMPORT_PATH_PREFIX = "/__imports__"
+
+    def initialize(theme_root: nil)
+      @theme_root = theme_root || Liquidbook.root
+      @data = load_config
+    end
+
+    # Returns HTML strings ready to inject into <head>
+    def head_tags_html
+      Array(@data["head"]).map { |entry| entry_to_html(entry) }
+    end
+
+    # Returns a map of serve_path => absolute_file_path for file imports
+    def import_files
+      @import_files ||= build_import_map
+    end
+
+    def port
+      @data["port"] || 4567
+    end
+
+    def host
+      @data["host"] || "127.0.0.1"
+    end
+
+    def [](key)
+      @data[key.to_s]
+    end
+
+    private
+
+    def load_config
+      path = File.join(@theme_root, ".liquid-preview", "config.yml")
+      return DEFAULT_CONFIG.dup unless File.exist?(path)
+
+      loaded = YAML.safe_load(File.read(path), permitted_classes: []) || {}
+      DEFAULT_CONFIG.merge(loaded)
+    end
+
+    def file_path?(entry)
+      # Not raw HTML, looks like a path
+      !entry.strip.start_with?("<") && entry.match?(/\.\w+$/)
+    end
+
+    def resolve_path(entry)
+      File.expand_path(entry.strip, @theme_root)
+    end
+
+    def serve_path(entry)
+      # Use resolved absolute path for a deterministic, safe URL
+      abs = resolve_path(entry)
+      safe_name = abs.gsub(/[^a-zA-Z0-9._-]/, "_")
+      "#{IMPORT_PATH_PREFIX}/#{safe_name}"
+    end
+
+    def entry_to_html(entry)
+      if file_path?(entry)
+        url = serve_path(entry)
+        ext = File.extname(entry.strip).downcase
+        case ext
+        when ".css"
+          %(<link rel="stylesheet" href="#{url}">)
+        when ".js", ".mjs", ".ts"
+          %(<script type="module" src="#{url}"></script>)
+        else
+          %(<link href="#{url}">)
+        end
+      else
+        entry.strip
+      end
+    end
+
+    def build_import_map
+      map = {}
+      Array(@data["head"]).each do |entry|
+        next unless file_path?(entry)
+
+        abs = resolve_path(entry)
+        map[serve_path(entry)] = abs
+      end
+      map
+    end
+  end
+end

data/lib/liquidbook/filters/shopify_filters.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Liquidbook
+  module Filters
+    # Common Shopify Liquid filters for local preview
+    module ShopifyFilters
+      # Asset URL filters
+      def asset_url(input)
+        "/assets/#{input}"
+      end
+
+      def asset_img_url(input, size = nil)
+        return input unless input.is_a?(String)
+
+        "/assets/#{input}"
+      end
+
+      def image_url(input, width: nil, height: nil, **_opts)
+        return "" unless input
+
+        src = input.is_a?(Hash) ? input["src"] : input.to_s
+        params = []
+        params << "width=#{width}" if width
+        params << "height=#{height}" if height
+        params.empty? ? src : "#{src}?#{params.join("&")}"
+      end
+
+      def img_tag(input, alt: "")
+        %(<img src="#{input}" alt="#{alt}" loading="lazy">)
+      end
+
+      # Money filters
+      def money(input)
+        return "" unless input
+
+        "¥#{format("%d", input.to_i)}"
+      end
+
+      def money_with_currency(input)
+        "#{money(input)} JPY"
+      end
+
+      # String filters (Shopify extensions)
+      def handle(input)
+        return "" unless input
+
+        input.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/^-|-$/, "")
+      end
+
+      def handleize(input)
+        handle(input)
+      end
+
+      def pluralize(input, singular, plural)
+        input.to_i == 1 ? singular : plural
+      end
+
+      # URL filters
+      def link_to(input, url, title = "")
+        title_attr = title.to_s.empty? ? "" : %( title="#{title}")
+        %(<a href="#{url}"#{title_attr}>#{input}</a>)
+      end
+
+      def within(url, collection_url)
+        "#{collection_url}#{url}"
+      end
+
+      def stylesheet_tag(url)
+        %(<link rel="stylesheet" href="#{url}" type="text/css">)
+      end
+
+      def script_tag(url)
+        %(<script src="#{url}"></script>)
+      end
+
+      # Collection / pagination helpers
+      def paginate(input, page_size)
+        input
+      end
+
+      def default_pagination(_input)
+        ""
+      end
+
+      # JSON / data
+      def json(input)
+        require "json"
+        input.to_json
+      end
+
+      # Translation stub
+      def t(input)
+        input.to_s
+      end
+
+      # Placeholder image
+      def placeholder_svg_tag(type)
+        %(<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><rect width="100" height="100" fill="#eee"/><text x="50" y="50" text-anchor="middle" dy=".3em" fill="#999">#{type}</text></svg>)
+      end
+
+      # Color filters
+      def color_to_rgb(input)
+        input.to_s
+      end
+
+      def color_modify(input, _attr, _value)
+        input.to_s
+      end
+
+      def color_to_hex(input)
+        input.to_s
+      end
+
+      def color_brightness(input)
+        128
+      end
+
+      # Font filters
+      def font_modify(input, _attr, _value)
+        input
+      end
+
+      def font_url(input)
+        ""
+      end
+
+      def font_face(input)
+        ""
+      end
+
+      # Media filters
+      def external_video_url(input, **_opts)
+        input.to_s
+      end
+
+      def media_tag(input, **_opts)
+        %(<div class="media-placeholder">#{input}</div>)
+      end
+
+      # Metafield
+      def metafield_tag(input)
+        input.to_s
+      end
+    end
+  end
+end

data/lib/liquidbook/mock_data.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Liquidbook
+  # Provides mock Shopify objects for template rendering
+  class MockData
+    DEFAULT_FIXTURES_PATH = File.expand_path("../../fixtures/default_mocks.yml", __dir__)
+
+    def initialize(theme_root: nil)
+      @theme_root = theme_root || Liquidbook.root
+      @data = load_data
+    end
+
+    def to_assigns
+      @data.dup
+    end
+
+    # Merge section schema defaults into the data
+    def with_section(schema_parser)
+      assigns = to_assigns
+      assigns["section"] = {
+        "settings" => schema_parser.default_settings,
+        "blocks" => schema_parser.default_blocks
+      }
+      assigns
+    end
+
+    private
+
+    def load_data
+      data = load_yaml(DEFAULT_FIXTURES_PATH)
+
+      # Override with user's custom mocks if present
+      user_mocks = File.join(@theme_root, ".liquid-preview", "mocks.yml")
+      data = deep_merge(data, load_yaml(user_mocks)) if File.exist?(user_mocks)
+
+      data
+    end
+
+    def load_yaml(path)
+      return {} unless File.exist?(path)
+
+      YAML.safe_load(File.read(path), permitted_classes: [Date, Time]) || {}
+    end
+
+    def deep_merge(base, override)
+      base.merge(override) do |_key, old_val, new_val|
+        if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+          deep_merge(old_val, new_val)
+        else
+          new_val
+        end
+      end
+    end
+  end
+end