# `MishkaCmsCore.CoreComponents`
[🔗](https://github.com/mishka-group/mishka_cms_core/blob/v0.0.1/lib/mishka_cms_core/core_components.ex#L5)

Provides core UI components.

At first glance, this module may seem daunting, but its goal is to provide
core building blocks for your application, such as tables, forms, and
inputs. The components consist mostly of markup and are well-documented
with doc strings and declarative assigns. You may customize and style
them in any way you want, based on your application growth and needs.

Styling is plain Tailwind CSS only — style components with Tailwind utilities
such as `flex`, `bg-*`, `rounded-*`, and `text-*`. Here are useful references:

  * [Tailwind CSS](https://tailwindcss.com) - the foundational framework
    we build on. You will use it for layout, sizing, flexbox, grid, and
    spacing.

  * [Heroicons](https://heroicons.com) - see `icon/1` for usage.

  * [Phoenix.Component](https://hexdocs.pm/phoenix_live_view/Phoenix.Component.html) -
    the component system used by Phoenix. Some components, such as `<.link>`
    and `<.form>`, are defined there.

# `button`

Renders a button with navigation support.

## Examples

    <.button>Send!</.button>
    <.button phx-click="go" variant="primary">Send!</.button>
    <.button navigate="/">Home</.button>
    <.button variant="soft" icon="hero-trash">Remove</.button>

`primary` is the page's one main action; `soft` is outlined, for the actions beside it; `accent`
is tinted, for the one of those worth drawing the eye to. `icon` is a hero icon before the label.

`type` is the button's HTML type. `"submit"` is what a button with no type already does, so it is
not written into the markup.

## Attributes

* `type` (`:string`) - Defaults to `"submit"`. Must be one of `"button"`, `"submit"`, or `"reset"`.
* `class` (`:string`)
* `variant` (`:string`) - Must be one of `"primary"`, `"soft"`, or `"accent"`.
* `icon` (`:string`) - Defaults to `nil`.
* Global attributes are accepted. Supports all globals plus: `["href", "navigate", "patch", "method", "download", "name", "value", "disabled"]`.
## Slots

* `inner_block` (required)

# `create_menu`

The page's own "+ Add …" button, with the other ways of making one behind a caret beside it.

THE MAIN HALF OPENS THE VISUAL EDITOR, because that is what making one usually means now: the
editor asks for the two or three things a record cannot exist without and then shows the structure
chooser. The long form — every field the resource declares — is still one click away under the
caret, for the times somebody wants to fill it in.

The menu is markup, shown by a JS command: nothing behind it needs the server, and a round trip to
open a two-item list would be a round trip that changes nothing. Each item closes it, because a
JS-shown element keeps a sticky `display` no later render can clear.

## Example

    <.create_menu
      id="add-page"
      label="+ Add Page"
      navigate="/admin/dashboard/runtime/builder/page"
      modal="page-form-modal"
    >
      <:way id="pb-create-form-page" label="Create with the full form" modal>
        Every field this resource has, on one form.
      </:way>
      <:way id="pb-create-open-page" label="Fill in the form, then open the editor" event="create_and_open">
        The same form, and the editor opens on what it saved.
      </:way>
    </.create_menu>

A `:navigate` way is a link and leaves; an `:event` way pushes that event to THIS page and then
opens the modal, so the page can remember what was asked for by the time the save arrives; a
`modal` way just opens it.

## Attributes

* `id` (`:string`) (required)
* `label` (`:string`) (required)
* `navigate` (`:string`) (required) - where the main half goes — the visual editor.
* `modal` (`:string`) (required) - the create modal the caret's items can open.
## Slots

* `way` - one other way to create, drawn under the caret. Accepts attributes:

  * `label` (`:string`) (required)
  * `modal` (`:boolean`) - the item opens the create modal.
  * `event` (`:string`) - an event this page handles, and then the modal opens.
  * `navigate` (`:string`) - a path — the item is a link and leaves.
  * `id` (`:string`)

# `flash`

Renders flash notices.

## Examples

    <.flash kind={:info} flash={@flash} />
    <.flash kind={:info} phx-mounted={show("#flash")}>Welcome Back!</.flash>

## Attributes

* `id` (`:string`) - the optional id of flash container.
* `flash` (`:map`) - the map of flash messages to display. Defaults to `%{}`.
* `title` (`:string`) - Defaults to `nil`.
* `kind` (`:atom`) - used for styling and flash lookup. Must be one of `:info`, or `:error`.
* Global attributes are accepted. the arbitrary HTML attributes to add to the flash container.
## Slots

* `inner_block` - the optional inner block that renders the flash message.

# `header`

Renders a header with title.

## Slots

* `inner_block` (required)
* `subtitle`
* `actions`

# `hide`

# `hide_modal`

# `icon`

Renders a [Heroicon](https://heroicons.com).

Heroicons come in three styles – outline, solid, and mini.
By default, the outline style is used, but solid and mini may
be applied by using the `-solid` and `-mini` suffix.

You can customize the size and colors of the icons by setting
width, height, and background color classes.

Icons are extracted from the `deps/heroicons` directory and bundled within
your compiled app.css by the plugin in `assets/vendor/heroicons.js`.

## Examples

    <.icon name="hero-x-mark" />
    <.icon name="hero-arrow-path" class="ms-1 size-3 motion-safe:animate-spin" />

## Attributes

* `name` (`:string`) (required)
* `class` (`:string`) - Defaults to `"size-4"`.

# `input`

Renders an input with label and error messages.

A `Phoenix.HTML.FormField` may be passed as argument,
which is used to retrieve the input name, id, and values.
Otherwise all attributes may be passed explicitly.

## Types

This function accepts all HTML input types, considering that:

  * You may also set `type="select"` to render a `<select>` tag

  * `type="checkbox"` is used exclusively to render boolean values

  * For live file uploads, see `Phoenix.Component.live_file_input/1`

See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input
for more information. Unsupported types, such as hidden and radio,
are best written directly in your templates.

## Examples

    <.input field={@form[:email]} type="email" />
    <.input name="my-input" errors={["oh no!"]} />

## Attributes

* `id` (`:any`) - Defaults to `nil`.
* `name` (`:any`)
* `label` (`:string`) - Defaults to `nil`.
* `value` (`:any`)
* `type` (`:string`) - Defaults to `"text"`. Must be one of `"checkbox"`, `"color"`, `"date"`, `"datetime-local"`, `"email"`, `"file"`, `"month"`, `"number"`, `"password"`, `"search"`, `"select"`, `"tel"`, `"text"`, `"textarea"`, `"time"`, `"url"`, or `"week"`.
* `field` (`Phoenix.HTML.FormField`) - a form field struct retrieved from the form, for example: @form[:email].
* `errors` (`:list`) - Defaults to `[]`.
* `checked` (`:boolean`) - the checked flag for checkbox inputs.
* `prompt` (`:string`) - the prompt for select inputs. Defaults to `nil`.
* `options` (`:list`) - the options to pass to Phoenix.HTML.Form.options_for_select/2.
* `multiple` (`:boolean`) - the multiple flag for select inputs. Defaults to `false`.
* `class` (`:string`) - the input class to use over defaults. Defaults to `nil`.
* `error_class` (`:string`) - the input error class to use over defaults. Defaults to `nil`.
* Global attributes are accepted. Supports all globals plus: `["accept", "autocomplete", "capture", "cols", "disabled", "form", "list", "max", "maxlength", "min", "minlength", "multiple", "pattern", "placeholder", "readonly", "required", "rows", "size", "step"]`.

# `list`

Renders a data list.

## Examples

    <.list>
      <:item title="Title">{@post.title}</:item>
      <:item title="Views">{@post.views}</:item>
    </.list>

## Slots

* `item` (required) - Accepts attributes:

  * `title` (`:string`) (required)

# `modal`

Renders a modal dialog.

## Examples

    <.modal id="my-modal">
      Modal content
    </.modal>

    <.modal id="my-modal" show on_cancel={JS.navigate(~p"/")}>
      Modal content
    </.modal>

Open programmatically: `JS.show(to: "#my-modal")`.
Close programmatically: `JS.exec("data-cancel", to: "#my-modal")`.

Its rounded box clips what it holds, but not while a control inside is expanded
(`aria-expanded="true"`): a form's relation list opened on the last field ran past the box's
bottom edge, and the box cut it off.

## Attributes

* `id` (`:string`) (required)
* `show` (`:boolean`) - Defaults to `false`.
* `on_cancel` (`Phoenix.LiveView.JS`) - Defaults to `%Phoenix.LiveView.JS{ops: []}`.
* `width_class` (`:string`) - Defaults to `"max-w-3xl"`.
* `padding_class` (`:string`) - Defaults to `"p-6"`.
## Slots

* `inner_block` (required)

# `present?`

Whether a relationship or field holds a value a template can read through.

A relationship nobody loaded is `%Ash.NotLoaded{}` and a field a policy hides is
`%Ash.ForbiddenField{}` — structs, so both are truthy, and `:if={@record.site}` waves them past the
guard the loaded record was meant to pass. The read behind it, `{@record.site.name}`, then raises
and takes the LiveView with it. Ask this instead:

    <span :if={present?(@record.site)}>{@record.site.name}</span>

# `roadmap_notice`

A roadmap notice: the `tip/1` box with a bold title over a line of text, for a part of the admin
that is not built yet or that shows sample content in its place.

`title` names what is not available. The inner block says that it is on the roadmap, and what the
sample content is, in the caller's own gettext.

## Examples

    <.roadmap_notice id="pb-ai-roadmap" title={gettext("The AI Assistant is not available yet")}>
      {gettext("This part of the editor is on our roadmap.")}
    </.roadmap_notice>

## Attributes

* `id` (`:string`) - Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* `title` (`:string`) (required)
## Slots

* `inner_block` (required)

# `select_chevron`

The chevron of a native `<select>`, 11px in from its end edge: the right in a left-to-right
page, the left in a right-to-left one.

Put it after the select inside a `relative` box. Give the select `appearance-none`, so the
browser draws no arrow of its own, and an end padding of at least `pe-8`, so the selected text
stops before the chevron.

## Examples

    <div class="relative">
      <select name="size" class="h-9 appearance-none rounded-[9px] border ps-3 pe-8">
        <option>20</option>
      </select>
      <.select_chevron />
    </div>

## Attributes

* `class` (`:any`) - classes added to the chevron's own. Defaults to `nil`.

# `show`

# `show_form_modal`

Shows the modal `id` with the Gervaz form inside it started over as an empty create form, the
form's defaults kept — what an "Add" button runs that opens a form modal on the client. `form` is
the form's resource, or its component id when the page mounts it under another one.

    <button phx-click={show_form_modal("post-form-modal", MyApp.Post)}>Add post</button>

A page that opens the modal from the server sends the form `reset: true` instead — see
`MishkaGervaz.Form.Web.Live`.

# `show_modal`

# `site_cell`

A record's site in an admin list: a globe and "Global" for a record every site shares, a server
and the site's name otherwise — the Site column the runtime lists draw.

    <MishkaCmsCore.CoreComponents.site_cell global?={is_nil(r.site_id)} name={r.site && r.site.name} />

## Attributes

* `global?` (`:boolean`) (required)
* `name` (`:string`) - Defaults to `nil`.

# `table`

Renders a table with generic styling.

## Examples

    <.table id="users" rows={@users}>
      <:col :let={user} label="id">{user.id}</:col>
      <:col :let={user} label="username">{user.username}</:col>
    </.table>

## Attributes

* `id` (`:string`) (required)
* `rows` (`:list`) (required)
* `row_id` (`:any`) - the function for generating the row id. Defaults to `nil`.
* `row_click` (`:any`) - the function for handling phx-click on each row. Defaults to `nil`.
* `row_item` (`:any`) - the function for mapping each row before calling the :col and :action slots. Defaults to `&Function.identity/1`.
## Slots

* `col` (required) - Accepts attributes:

  * `label` (`:string`)
* `action` - the slot for showing user actions in the last table column.

# `tip`

A short tip beside what it explains: a light amber box, a small speech-bubble glyph and small
text. The builder's sheets, its SEO tab and a page's settings draw their notes with it.

## Examples

    <.tip id="pb-seo-record-note" class="mt-3">Each record fills what you leave empty.</.tip>

## Attributes

* `id` (`:string`) - Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted. the arbitrary HTML attributes to add to the tip's box.
## Slots

* `inner_block` (required)

# `translate_error`

Translates an error message using gettext.

# `translate_errors`

Translates the errors for a field from a keyword list of errors.

---

*Consult [api-reference.md](api-reference.md) for complete listing*