<unit-number></unit-number>
~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Typical usage

  <script src=https://pawjy.github.io/html-unit-number/src/unit-number.js async></script>
  <link rel=stylesheet href=https://pawjy.github.io/html-unit-number/css/default.css>

  <!-- Static -->
  <unit-number type=distance><number-value>100</number-value><number-unit>m</number-unit></unit-number>

  <!-- Script-inserted -->
  <unit-number type=elevation value=3776></unit-number>

* Element semantics

  unit-number

    A |unit-number| element represents a number with unit.  It is a
    phrasing content, flow content, and palpable content.  Its content
    model is one or more sequence of |number-value|, |number-sign|,
    |number-unit|, and |number-separator| elements.

  number-sign

    A |number-sign| element represents the sign part of the parent
    |unit-number| element.  If the parent is not a |unit-number|
    element, the element represents its content.  Its content model is
    phrasing content.  It may contain any character sequence directly
    or indirectly, which as a whole represents a sign suitable for
    human consumption.  Note that signs can be any string acts as sign
    indicator for the purpose of the |unit-number|'s type, including
    but not limited to: |+|, |-|, |－|, |▲|, |N|, and |東経|.

  number-value

    A |number-value| element represents the number part of the parent
    |unit-number| element.  If the parent is not a |unit-number|
    element, the element represents its content.  Its content model is
    phrasing content.  It may contain any character sequence directly
    or indirectly, which as a whole represents a number suitable for
    human consumption.

  number-unit

    A |number-unit| element represents the unit part of the parent
    |unit-number| element.  If the parent is not a |unit-number|
    element, the element represents its content.  Its content model is
    phrasing content.  It may contain any character sequence directly
    or indirectly, which as a whole represents a unit suitable for
    human consumption.

  number-separator

    A |number-separator| element represents a separator between
    elements within the parent |unit-number| element.  If the parent
    is not a |unit-number| element, the element represents its
    content.  Its content model is phrasing content.  It may contain
    any character sequence directly or indirectly, which as a whole
    represents a separator suitable for human consumption.

* Dynamic content expansion

The |unit-number.js| script in the |src| directory of this Git
repository implements the |unit-number| element.  It can be loaded by
the usual way:

  <script src=https://pawjy.github.io/html-unit-number/src/unit-number.js async></script>

This |script| element can be inserted, whenever desired, into anywhere
in the document in question.  It mutates the content of any
|unit-number| element in the document (including any |unit-number|
element inserted thereafter) with |type| attribute, representing
human-readable equivalent to |value| attribute value.  The content is
also to be updated whenever the |value| attribute value is updated.
Any existing content of the element is discarded.

The |unit-number| element's |value| attribute value must be a
JavaScript floating point number string.  The value of a |unit-number|
element is the result of the JavaScript |parseFloat| function's return
value when applied to the |value| attribute value.

The |unit-number| element's |type| attribute value can be one of
following:

  bytes

    The element represents a length of binary data.  The value of the
    element is the number of the bytes.

  count

    The element represents a count, i.e. the number of something.  The
    value of the element is the count.

  distance

    The element represents a distance.  The value of the element is
    the distance in meters.

    This type supports the |delta| attribute.  If specified, the sign
    is shown even when the value is non-negative (i.e. |+|).

  duration

    The element represents a duration.  The value of the element is
    the duration in seconds.

    This type supports the |format| attribute with following values:

      h:mm:ss.ss (default)

        The duration is represented by the concatenation of the number
        of hours, minutes, and seconds, separated by ":" characters,
        followed by 1/100 seconds, where minutes, seconds, and 1/100
        seconds are zero-padded.

      hh:mm:ss.ss

        Similar to |h:mm:ss.ss| but the hour is zero-padded when it is
        less than 10.

      h:m:s.ss

        Similar to |h:mm:ss.ss| but no zero-padding for minutes and
        seconds.

      h:mm:ss

        The duration is represented by the concatenation of the number
        of hours, minutes, and seconds, separated by ":" characters,
        where minutes and seconds are zero-padded.  Fractional part of
        seconds is truncated.

      hh:mm:ss

        Similar to |h:mm:ss| but the hour is zero-padded when it is
        less than 10.

      h:m:s

        Similar to |h:mm:ss| but no zero-padding for minutes and
        seconds.

      h:mm

        The duration is represented by the concatenation of the number
        of hours and minutes, separated by a ":" character, where
        minutes are zero-padded.

      hh:mm

        Similar to |h:mm| but the hour is zero-padded.

      h:m

        Similar to |h:mm| but no zero-padding for minutes.

  elevation

    The element represents an elevation.  The value of the element is
    the elevation in meters.

    Unlike the |distance| type, units kilometers and miles are not
    used.

    This type supports the |delta| attribute.  If specified, the sign
    is shown even when the value is non-negative (i.e. |+|).

  lat

    The element represents a latitude.  The value of the element is
    the latitude in degrees.

  lon

    The element represents a longitude.  The value of the element is
    the longitude in degrees.

  percentage

    The element represents a ratio as percentage (%).  The value of
    the element is the ratio, where |0| represents 0% and |1|
    represents 100%.

  pixels

    The element represents a length as CSS pixel.  The value of the
    element is the number of CSS pixels.

  rank

    The element represents a rank (as in ranking).  The value of the
    element is the rank number.

  yen

    The element represents a price in Japanese Yen (JPY, 日本円).
    The value of the element is an integer of the yen.

    Note that this implements the serialize a number in
    CJK-10000-grouped number string
    <https://manakai.github.io/spec-numbers/#serialize-a-number-in-cjk-10000-grouped-number-string>
    algorithm (except number units greater than 京 are not used).

Types |distance| and |elevation| support Metric and Imperial unit
systems:

  If the document's document element (i.e. the |html| element) has a
  |data-distance-unit| attribute whose value is |imperial|, the
  content is generated using the imperial system units (e.g. miles).
  Otherwise, the metric system units are used.

  However, if the |unit-number| element has the |altunit| attribute
  specified, the another unit system is selected.

Types |count| and |rank| support the |unit| attribute.  If there is a
|unit| attribute, its value is used as the unit.  If the unit begins
with an ASCII letter, a SPACE character is inserted between the number
and the value and a |hasseparator| boolean attribute is specified to
the |unit-number| element.

Type |duration| supports the |unit| attribute.  If the |unit|
attribute value is |時間|, the content is formatted using Japanese
style, e.g. "12時間30分03秒41".

* Author

Wakaba <wakaba@suikawiki.org>.

* History

The repository was located at
<https://github.com/wakaba/html-unit-number> until R7.9.19 (19
September 2025), then transferred to
<https://github.com/pawjy/html-unit-number>.

* License

unit-number.js: AGPL.  See its comment.

Other files:

Per CC0 <https://creativecommons.org/publicdomain/zero/1.0/>, to the
extent possible under law, the author has waived all copyright and
related or neighboring rights to the files in this repository unless
otherwise stated.