Panel API: CSS #242

taufik-nurrohman · 2022-09-17T09:05:16Z

taufik-nurrohman
Sep 17, 2022
Maintainer

This article is a draft and will be moved to the official web site when the API is matured.

This concept acts as a communication bridge between the developer (human) and the code, with the hope that human can get the idea of what the code will do when they skim through it. Some of the concepts here may not be implemented in the core Panel extension, but they will be a standard guide that developers need to follow to ensure the application runs as it should.

API is dominated by standardized HTML classes, and some HTML data-* attributes in case classes are unable to describe the intent and purpose of the command. Standard HTML class format on the panel consists of adjectives, separated by a colon; making it look like key-value pairs of an object.

<html class="can:fetch has:comment is:page not:art">
  …
</html>

Some are also used to express nouns. Usually preceded by content: or lot: prefix. About why I chose content and lot as a prefix is related to content and lot data which is very common in the components. The HTML output generated by content data should be given class content and the HTML output generated by lot data should be given class lot.

Class content indicates that the element contains a non-collection data, while class lot describes that the element contains a collection data.

<div class="content"> … </div>

<ul class="lot">
  <li class="content"> … </li>
  <li class="content"> … </li>
  <li class="content"> … </li>
</ul>

However, you don’t have to apply this class to all elements. A set of elements formed by a WYSIWYG application, or elements rendered from Markdown syntax do not need to apply these classes. In most cases, it would be more appropriate to use WAI-ARIA attributes as a marker so that it can be selected by CSS using attribute selectors.

Base

Base styles serve to normalize the appearance of miscellaneous elements such as paragraphs, headings, links, tables, forms, etc. They mostly don’t target classes but rather make use of attributes and pseudo classes/elements.

Classes

Adjective

Prefix	Role
`as`	Can be used to express roles. For example `as:button`, `as:link`, `as:text`, `as:user`.
`are`	Can be used to express the nature of a group. For example `are:active`.
`can`	Can be used to express ability or empowerment. For example `can:fetch`, `can:flex`, `can:sort`.
`has`	Can be used to express ownership. For example `has:description`, `has:icon`, `has:shadow`, `has:title`.
`is`	Can be used to express the nature of an individual. For example `is:active`, `is:current`.
`not`	Can be used to express the nature of an individual, in a negative context. For example `not:active`, `not:vital`.
`of`	Can be used to express connection. For example `of:user`.
`with`	Can be used to express involvement. For example `with:fields`, `with:options`.

Note: Class is:flex indicates that child elements are arranged horizontally. When the container width is no longer able to accommodate, then the child elements will be flowed down just the way text flows. Class can:flex is also the same, but in narrow container conditions, the horizontal styling may be forced to be vertical styling by media queries. Or vice-versa, you can make them arranged vertically by default, and in narrow container conditions, make them arranged horizontally. In essence, using this class should indicate that the child elements can be arranged horizontally if certain conditions are met.

Noun

Prefix	Role
`content`	Represents the content area of the component. May contain data passed from `$page->content`.
`description`	Represents the description area of the component. May contain data passed from `$page->description`.
`figure`	TODO
`icon`	Represents the icon of the component. May contain data passed from `$page->icon`.
`image`	Represents the image of the component. May contain data passed from `$page->image`.
`lot`	Represents a list of components.
`status`	Represents the status data of the component. Can be used as a wrapper of a badge notification for new items count, placed after the menu title.
`title`	Represents the title area of the component. May contain data passed from `$page->title`.

Example:

<article>
  <h2 class="title">
    <svg class="icon">
      <path d="<?= $page->icon; ?>"></path>
    </svg>
    <span>
      <?= $page->title; ?>
    </span>
    <data class="status" role="status" value="<?= $page->comments->count; ?>">
      <?= $page->comments->title; ?>
    </data>
  </h2>
  <p class="description">
    <?= $page->description; ?>
  </p>
  <div class="content">
    <figure>
      <img class="image" src="<?= $page->image; ?>">
    </figure>
    <?= $page->content; ?>
  </div>
</article>

Quantity

Prefix	Role
`count`	Provides information regarding the number of items in a component.

Class content and lot is usually followed by class count:* where * indicates the number of items in it. Not all child elements are considered items. Title and description that inevitably have to be in the container may not need to be taken into account. The developer is free to determine if a component is empty or contains.

<div class="content count:1"> … </div>

<ul class="count:3 lot">
  <li class="content count:1"> … </li>
  <li class="content count:1"> … </li>
  <li class="content count:1"> … </li>
</ul>

The purpose of this information is to communicate with CSS easily. For example, when a tabs component has only one trigger tab, the designer may want to hide the tabs row because tab switching ability is no longer relevant when there is only one trigger tab in the component.

.count\:0.lot\:tabs [role='tablist'],
.count\:1.lot\:tabs [role='tablist'] {
  display: none;
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Mecha

Panel API: CSS #242

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 1 comment

Select a reply

Uh oh!

Mecha

Panel API: CSS #242

Uh oh!

Uh oh!

taufik-nurrohman Sep 17, 2022 Maintainer

Base

Classes

Adjective

Noun

Quantity

Replies: 1 comment

taufik-nurrohman
Sep 17, 2022
Maintainer