Skip to content

About

Mishka Gervaz is a comprehensive, declarative UI library for the Ash ecosystem, define tables, forms, and data-driven interfaces entirely through DSL, with built-in sorting, filtering, real-time updates, and extensible templates. Every component, and adapter is fully overridable and customizable.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Β 
Β 

Latest commit

Β 

History

58 Commits

Folders and files

Repository files navigation

πŸͺ„ MishkaGervaz

A comprehensive, declarative UI library for the Ash Framework β€” define admin tables, forms, and data-driven interfaces entirely through DSL. ✨

Hex.pm Hex Downloads License GitHub Sponsors Buy Me a Coffee


Warning

🚧 Status β€” alpha. APIs are still evolving and the library is not yet recommended for production. Track progress on GitHub and the CHANGELOG.


πŸ“– Table of contents


πŸ’­ Why MishkaGervaz?

Building admin UIs around an Ash resource is repetitive: list views, filters, sorting, pagination, edit forms, validation, multi-step wizards, file uploads, master / tenant access control. Each surface calls the same building blocks in slightly different ways.

MishkaGervaz collapses that into a DSL. Declare what your admin surface looks like β€” fields, columns, filters, steps, uploads, access rules β€” and the library builds the LiveView, wires events, runs queries, handles form state, and renders through a swappable UI adapter. Every component, behaviour, and adapter is overridable; nothing is hidden.

mishka_gervaz do
  table do
    identity do
      name :posts
      route "/admin/dashboard/blog/posts"
    end

    columns do
      column :title do
        sortable true
        label fn -> dgettext("blog", "Title") end
      end

      column :status do
        label fn -> dgettext("blog", "Status") end
      end
    end

    filters do
      filter :search, :text, fields: [:title, :slug]
      filter :status, :select do
        options [{"Published", :published}, {"Draft", :draft}]
      end
    end
  end

  form do
    fields do
      field :title do
        required true
        ui do
          label fn -> dgettext("blog", "Title") end
        end
      end

      field :status do
        options [{"Draft", :draft}, {"Published", :published}]
      end
    end
  end
end

That's the whole admin surface for a resource. Add a route, render the LiveComponent, and you have a working list page with create / edit forms, filters, sort, master / tenant access gates, and PubSub-powered real-time updates. πŸš€


✨ Highlights

πŸ“Š Tables

  • 🎨 Columns by atom or module β€” built-ins for :text, :number, :boolean, :date, :datetime, :enum, :tags, :money, :url, :image, :json, :uuid, :array, plus a registry that accepts any custom column module.
  • πŸ” Filters as first-class entities β€” text, select, multi-select, date range, number range, boolean, relation (with search / load-more / static modes), with predicate operators (contains, equals, gt, lt, between, …).
  • πŸ“‘ Pagination β€” numbered, load-more, infinite-scroll. Configurable page size, page-size options, max page size.
  • ↕️ Sorting β€” declarative, multi-column, deep-link-friendly.
  • πŸ”— URL sync β€” page state (filters, sort, page, search) round-trips through the URL so refresh and copy-paste-link both work.
  • ⚑ Real-time β€” wire pubsub and rows update live without manual subscriptions.
  • πŸ“¦ Bulk actions β€” :destroy, :unarchive, :permanent_destroy, plus your own per-resource handlers.
  • 🎯 Row actions β€” custom buttons / links per row, with master / tenant gating.
  • πŸ—„οΈ Archive support β€” soft-delete column, restore action, master-vs-tenant action mapping.
  • ✨ Auto-detect from Ash attributes β€” auto_columns true builds a sensible default column set so you can opt in incrementally.

πŸ“ Forms

  • 🧩 Field types β€” :text, :textarea, :password, :select, :multi_select, :checkbox, :toggle, :date, :datetime, :range, :number, :hidden, :file, :upload, :relation, :json, :nested, :array_of_maps, :string_list, :combobox, plus arbitrary custom modules.
  • πŸͺœ Layout modes β€” :standard, :wizard (sequential steps), :tabs (free navigation).
  • πŸ“‚ Groups β€” visually section fields with optional collapsibles.
  • βœ… Validation β€” driven by Ash actions; phx-change validation surfaces field-level errors automatically.
  • πŸͺ Lifecycle hooks β€” on_init, on_validate, before_save, after_save, on_cancel, on_change, plus per-field JS hooks.
  • πŸ’¬ Notices β€” info / warning / error / success banners with positions, group anchoring, step targeting, dismiss, and visibility predicates.
  • 🎩 Header / footer chrome β€” title, description, content, icon, class, and dynamic show/hide.
  • πŸ“Ž Uploads β€” drop-zone or button styles; multi-file; auto-namespaced names so multiple form components on one page never collide; existing-files list + delete.
  • πŸ”— Relations β€” static (load all), search (autocomplete), search-multi, load-more pagination; with display_field, value_field, search_field, min_chars, debounce, custom load fn for tenant filtering.
  • πŸͺΊ Constrained-map nested fields β€” array-of-maps without changing your DB shape; add / remove rows; per-sub-field validation.
  • πŸ” Per-mode access control β€” restricted: true for master-only fields, function predicates for fine-grained gating, per-action :create / :update rules.
  • πŸ‘₯ Master / tenant action tuples β€” read {:master_get, :read} style; the same DSL drives different Ash actions depending on the user.

🌍 Cross-cutting

  • 🎨 UI adapter β€” pluggable component layer. Tailwind adapter ships in; swap in your own to render against any design system.
  • πŸ”§ Override surface β€” every state builder, event handler, data loader, template, and adapter is defoverridable. Replace just one piece, all of them, or wire it via the DSL (state do field MyMod end).
  • 🌐 i18n β€” Gettext baked in; every label resolves through Gettext so translations land in the right places.
  • πŸ§ͺ Fully tested core β€” verifiers, transformers, sub-handlers, and helpers each have direct unit tests on top of integration tests; over 3,600 tests on the suite at the time of writing.

πŸš€ Installation

Add to your mix.exs:

def deps do
  [
    {:mishka_gervaz, "~> 0.0.1-alpha.1"},
    {:ash, "~> 3.0"},
    {:ash_phoenix, "~> 2.3"},
    {:phoenix_live_view, "~> 1.0"}
  ]
end

Fetch and compile:

mix deps.get
mix compile

Add the extension to your domain β€” set defaults that every resource in the domain inherits:

defmodule MyApp.Blog do
  use Ash.Domain,
    extensions: [MishkaGervaz.Domain]

  mishka_gervaz do
    table do
      actor_key :current_user
      ui_adapter MishkaGervaz.UIAdapters.Tailwind

      pagination do
        type :numbered
        page_size 20
        page_size_options [20, 50, 100]
      end

      realtime do
        pubsub MyApp.PubSub
      end

      actions do
        read {:master_read, :read}
        get {:master_get, :read}
        destroy {:master_destroy, :destroy}
      end

      archive do
        read_action {:master_archived, :archived}
        get_action {:master_get_archived, :get_archived}
        restore_action {:master_unarchive, :unarchive}
        destroy_action {:master_permanent_destroy, :permanent_destroy}
      end
    end

    form do
      actions do
        create {:master_create, :create}
        update {:master_update, :update}
        read {:master_get, :read}
      end

      submit do
        create label: fn -> dgettext("blog", "Create") end
        update label: fn -> dgettext("blog", "Save Changes") end
        cancel label: fn -> dgettext("blog", "Cancel") end
        position :bottom
      end
    end
  end

  resources do
    resource MyApp.Blog.Post
  end
end

Then add the resource extension:

defmodule MyApp.Blog.Post do
  use Ash.Resource,
    domain: MyApp.Blog,
    extensions: [MishkaGervaz.Resource]

  # ... your attributes / actions / relationships
end

🎯 Quick start

πŸ“Š A table

mishka_gervaz do
  table do
    identity do
      name :posts
      route "/admin/dashboard/blog/posts"
    end

    source do
      preload do
        always [:site, :tag_count, :comment_count]
      end
    end

    columns do
      column :title do
        sortable true

        render fn value ->
          assigns = %{title: value}
          ~H"<span class=\"font-semibold\">{@title}</span>"
        end
      end

      column :site_id do
        static true
        requires [:site_id, :site]
        label fn -> dgettext("blog", "Site") end
      end

      column :status do
        sortable true
        sort_field [:status]
      end

      column :inserted_at do
        sortable true
      end
    end

    filters do
      filter :search, :text, fields: [:title, :slug, :excerpt]

      filter :site_id, :relation do
        mode :search_multi
        display_field :name
        search_field :name
        restricted true
      end

      filter :status, :select do
        options [
          {"Published", :published},
          {"Draft", :draft},
          {"Archived", :archived}
        ]
      end
    end

    row_actions do
      action :edit do
        type :edit
        visible :active

        ui do
          icon "hero-pencil-square"
          class "text-blue-600 hover:bg-blue-50"
        end
      end

      action :archive do
        type :destroy
        confirm "Archive this post?"
        visible :active
      end

      action :unarchive do
        type :unarchive
        confirm "Restore this post?"
        visible :archived
      end
    end

    bulk_actions do
      action :archive, type: :destroy, confirm: "Archive selected posts?"

      action :unarchive,
        type: :unarchive,
        confirm: "Restore selected posts?",
        visible: :archived
    end

    url_sync do
      mode :bidirectional
      params [:filters, :sort, :page, :search]
      prefix "posts"
    end
  end
end

🎬 Mount it:

<.live_component
  module={MishkaGervaz.Table.Web.Live}
  id="posts-table"
  resource={MyApp.Blog.Post}
  current_user={@current_user}
/>

πŸ“ A form

mishka_gervaz do
  form do
    identity do
      name :post_form
    end

    source do
      preload do
        master [:master_collections, :master_tags]
        tenant [:tenant_collections, :tenant_tags]
      end
    end

    fields do
      field :title do
        required true

        ui do
          label fn -> dgettext("blog", "Title") end
          placeholder "Post title"
        end
      end

      field :status do
        options [
          {"Draft", :draft},
          {"Published", :published},
          {"Scheduled", :scheduled}
        ]
      end

      field :language, :combobox do
        options fn ->
          MyApp.Repo.distinct_languages()
          |> Enum.map(fn lang -> {String.upcase(lang), lang} end)
        end

        ui do
          label fn -> dgettext("blog", "Language") end
          placeholder "en, fa, ar, ..."
        end
      end

      field :site_id, :relation do
        mode :search
        display_field :name
        search_field :name
        restricted true
        show_on :create

        ui do
          label fn -> dgettext("blog", "Site") end
        end
      end

      field :tag_ids, :relation do
        virtual true
        resource MyApp.Blog.Tag
        mode :search_multi
        display_field :name
        search_field :name
        depends_on :site_id

        load fn query, state ->
          site_id =
            if state.master_user?,
              do: Map.get(state.field_values, :site_id),
              else: state.current_user.site_id

          Ash.Query.filter_input(query, %{site_id: site_id})
        end
      end

      field :body, :textarea do
        required true

        ui do
          label fn -> dgettext("blog", "Body") end
        end
      end
    end

    groups do
      group :basic_info do
        fields [:title, :status, :language]

        ui do
          label fn -> dgettext("blog", "Basics") end
        end
      end

      group :relationships do
        fields [:site_id, :tag_ids]

        ui do
          label fn -> dgettext("blog", "Relationships") end
        end
      end

      group :content do
        fields [:body]

        ui do
          label fn -> dgettext("blog", "Content") end
        end
      end
    end

    uploads do
      upload :cover do
        accept "image/*"
        max_file_size 5_000_000
      end
    end
  end
end

🎬 Mount it:

<.live_component
  module={MishkaGervaz.Form.Web.Live}
  id="post-form"
  resource={MyApp.Blog.Post}
  current_user={@current_user}
  record_id={@post_id}
/>

πŸͺœ A wizard or tabbed multi-step form is a one-block change:

layout do
  mode :wizard            # or :tabs

  step :basics do
    groups [:basic_info]
  end

  step :metadata do
    groups [:relationships]
  end

  step :content do
    groups [:content]
  end

  step :review do
    summary true
  end
end

πŸ”§ Customization & overrides

Three layers, each independent.

1️⃣ Per-callback override via use

defmodule MyApp.Form.SubmitHandler do
  use MishkaGervaz.Form.Web.Events.SubmitHandler

  def transform_params(state, params) do
    params
    |> super(state)
    |> Map.put("ingested_at", DateTime.utc_now())
  end
end

super falls through to the default. Every callback in every sub-builder is defoverridable.

2️⃣ Wire your override via DSL

mishka_gervaz do
  form do
    events do
      submit MyApp.Form.SubmitHandler
      validation MyApp.Form.ValidationHandler
    end

    state do
      field MyApp.Form.FieldBuilder
    end

    data_loader do
      relation MyApp.Form.RelationLoader
    end
  end
end

The DSL config is read at runtime by the orchestrator β€” no recompiling the macro tree.

3️⃣ Replace an entire subsystem module

mishka_gervaz do
  form do
    events MyApp.CustomFormEvents
    state module: MyApp.CustomState
  end
end

πŸ“š See the moduledocs of MishkaGervaz.Form.Web.State, MishkaGervaz.Form.Web.Events, MishkaGervaz.Form.Web.DataLoader, and the table-side counterparts for the full override surface.


πŸ—οΈ Architecture

                +----------------------------+
                | Phoenix.LiveComponent      |
                | (Form.Web.Live /           |
                |  Table.Web.Live)           |
                +--------------+-------------+
                               |
       +-----------+-----------+-----------+-----------+
       |           |           |           |           |
       v           v           v           v           v
   +-------+   +-------+   +-------+   +-------+   +-------+
   | State |   | Events|   |DataLdr|   |Render |   |Adapter|
   +-------+   +-------+   +-------+   +-------+   +-------+
       |           |           |           |           |
       v           v           v           v           v
   sub-builders  sub-handlers  sub-builders templates  components
   (5)           (7)           (4)          (Standard) (Tailwind / yours)
  • 🧠 State β€” single struct per LiveComponent, partitioned into static (config, never re-renders) and dynamic (form, errors, current_step, …). Sub-builders for fields, groups, steps, presentation, access β€” each defoverridable.
  • 🚚 DataLoader β€” async record loading, AshPhoenix.Form construction, relation option loading, hook execution. Sub-builders: RecordLoader, RelationLoader, TenantResolver, HookRunner.
  • πŸ“‘ Events β€” dispatch table for every phx- event the component sees. Sub-handlers: sanitization, validation, submit, step navigation, uploads, relation search, hooks.
  • 🎬 Renderer β€” thin bridge between LiveComponent and Templates; passes the static / dynamic split through so LiveView's diffing engine can skip work.
  • 🎨 UI adapter β€” the leaf layer that turns "render a button / a select / a stepper" into actual markup. Swap to retheme without touching the rest.

πŸ“š Documentation

  • πŸ“– API docs β€” hexdocs.pm/mishka_gervaz (published with each release).
  • 🧭 Guides β€” every public module ends its @moduledoc with a "See also" cross-link to its siblings, so navigation through the codebase stays close to the runtime call graph.
  • πŸ”¬ Reference resources β€” the test fixtures under test/support/resources/ show every DSL feature in working form.

🀝 Contributing

Issues, PRs, and design discussions are welcome.

git clone https://github.com/mishka-group/mishka_gervaz.git
cd mishka_gervaz
mix deps.get
mix test

Before opening a PR:

  • βœ… mix test β€” full suite green
  • βœ… mix format β€” formatter passes
  • βœ… mix dialyzer β€” type analysis clean (where applicable)

For larger feature work, please open an issue first so we can align on the design. πŸ’¬


πŸ’– Funding & sponsorship

MishkaGervaz is open-source software developed by Mishka Group. If your team or company benefits from this work, please consider supporting continued development:

GitHub Sponsors Β Β Β  Buy Me a Coffee

β˜• Donate / sponsor: github.com/sponsors/mishka-group Β· buymeacoffee.com/mishkagroup

Sponsorship directly funds maintenance, new features, and documentation. Thank you. πŸ’š


πŸ“œ License

Apache License 2.0 β€” see LICENSE.

Copyright Β© Mishka Group and contributors.

About

Mishka Gervaz is a comprehensive, declarative UI library for the Ash ecosystem, define tables, forms, and data-driven interfaces entirely through DSL, with built-in sorting, filtering, real-time updates, and extensible templates. Every component, and adapter is fully overridable and customizable.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages