Merge pull request #671 from gethinode/validation

Improve argument validation and documentation

data/structures/card.yml

@@ -17,14 +17,14 @@ arguments:
       type: url
       optional: true
       comment: >-
-        Optional address for the button or hyperlink.
+        Address for the button or hyperlink.
       group: partial
     class:
       type: string
       optional: true
       parent: merge
       comment: >-
-        Optional class attribute of the card element, e.g. “w-50”.
+        Class attribute of the card element, e.g. “w-50”.
     color:
       type: select
       optional: true
@@ -51,7 +51,7 @@ arguments:
       default: auto
       parent: cascade
       comment: >-
-        Optional padding of the content.
+        Padding of the content.
       options:
         values:
           - "0"
@@ -82,7 +82,7 @@ arguments:
       default: full
       parent: cascade
       comment: >-
-        Optional header components of the card, displayed in small caps. 
+        Header components of the card, displayed in small caps. 
       options:
         values:
           - full
@@ -95,7 +95,7 @@ arguments:
       default: none
       parent: cascade
       comment: >-
-        Optional footer components of the card, displayed in small caps.
+        Footer components of the card, displayed in small caps.
       options:
         values:
           - full
@@ -108,7 +108,7 @@ arguments:
         - template.HTML
       optional: true
       comment: >-
-        Optional description of the card.
+        Description of the card.
       group: partial
     loading:
       type: select
@@ -128,7 +128,7 @@ arguments:
       type: path
       optional: true
       comment: >-
-        Optional thumbnail image url, displayed on top or the left of the card.
+        Thumbnail image url, displayed on top or the left of the card.
     ratio:
       type: select
       optional: true
@@ -146,6 +146,7 @@ arguments:
     alt:
       type: string
       optional: true
+      release: v0.19.0
       comment: >-
         Alternate text for the thumbnail, uses "title" by default.
     icon:
@@ -169,5 +170,5 @@ arguments:
 body:
   optional: true
   comment: >-
-    Optional description of the card.
+    Description of the card.
   group: shortcode

exampleSite/hugo_stats.json

@@ -314,6 +314,7 @@
       "pb-4",
       "pb-5",
       "pb-md-0",
+      "pe-1",
       "pe-3",
       "position-absolute",
       "position-fixed",

layouts/partials/assets/button.html

@@ -67,7 +67,7 @@
 {{- with .badge }}{{ $badge = . }}{{ end -}}
 
 {{- $label := "" -}}
-{{- with .label }}{{ $label = . }}{{ end -}}
+{{- if .label }}{{ $label = .label }}{{ else }}{{ $label = $title }}{{ end -}}
 
 {{- $tooltip := "" -}}
 {{- if not (strings.HasSuffix $state "active") -}}
@@ -143,7 +143,8 @@
 
 {{- $attributes := .attributes -}}
 
-<a aria-label="{{ (or $label $title) | safeHTML }}" {{ if ne $state "disabled" }}{{ with $href }}href="{{ . }}"{{ end }}{{ end -}}
+<a aria-label="{{ (or $label $title) | safeHTML }}"
+    {{ if ne $state "disabled" }}{{ with $href }}href="{{ . }}"{{ end }}{{ end -}}
     {{- with $id }} id="{{ . }}"{{ end -}}
     {{- with $target }} target="{{ . }}"{{ end }}{{ with $rel }} rel="{{ . }}"{{ end -}}
     {{- with $toast }} data-toast-target="{{ $toast }}"{{ end -}}

layouts/partials/utilities/IsInvalidArgs.html

@@ -14,11 +14,7 @@
     {{ $error =  true }}
 {{ end }}
 
-{{ $args := .args }}
-{{ if not $args }}
-    {{- errorf "partial [utilities/ValidateArgs.html] - Missing value for param 'args'" -}}
-    {{ $error =  true }}
-{{ end }}
+{{ $args := .args | default slice }}
 
 {{ $definitions := (index site.Data.structures $structure).arguments }}
 {{ if not $definitions }}
@@ -40,15 +36,11 @@
         {{ end }}
         {{ if $extra }}{{ $expected = $expected | append $extra }}{{ end }}
         {{ $actual := printf "%T" $val }}
-        {{ if not (in $expected $actual ) }}
-            {{ warnf "[%s] argument '%s': expected type '%s', got '%s'" $structure $key (delimit $expected ", ") $actual }}
-            {{ $error = true }}
-        {{ end }}
-
-        {{/* validate required argument */}}
-        {{ if and (not $def.optional) (not $val) }}
-            {{ warnf "[%s] argument '%s': expected value" $structure $key }}
-            {{ $error = true }}
+        {{ if $val }}
+            {{ if not (in $expected $actual ) }}
+                {{ warnf "[%s] argument '%s': expected type '%s', got '%s'" $structure $key (delimit $expected ", ") $actual }}
+                {{ $error = true }}
+            {{ end }}
         {{ end }}
 
         {{/* validate permitted values */}}
@@ -69,6 +61,16 @@
             {{ end }}
         {{ end }}
     {{ end }}
+
+    {{/* validate required arguments */}}
+    {{ range $key, $val := $definitions }}
+        {{ if not $val.optional }}
+            {{ if not (in $args $key )}}
+                {{ warnf "[%s] argument '%s': expected value" $structure $key }}
+                {{ $error = true }}
+            {{ end }}
+        {{ end }}
+    {{ end }}
 {{ end }}
 
 {{ return $error }}

layouts/shortcodes/args.html

@@ -36,6 +36,13 @@
             {{ if not $val.optional }}{{ $required = "yes" }}{{ end }}
 
             {{ $comment := $val.comment }}
+            {{ if $val.deprecated }}
+                {{ $comment = printf `{{< release version="%s" short="true" size="sm" inline="true" state="deprecated" >}} %s` $val.deprecated $comment }}
+            {{ end }}
+            {{ if $val.release }}
+                {{ $comment = printf `{{< release version="%s" short="true" size="sm" inline="true" >}} %s` $val.release $comment }}
+            {{ end }}
+
             {{ $min := "" }}
             {{ $max := "" }}
             {{ if and $val.options.values (eq $type "select") }}
@@ -57,5 +64,5 @@
         {{ end }}
     {{ end }}
 
-    {{ partial "assets/table" (dict "page" .Page "input" $table "args" slice) }}
+    {{ partial "assets/table.html" (dict "page" .Page "input" $table "args" slice) }}
 {{ end }}

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@gethinode/hinode",
-  "version": "0.22.0-alpha",
+  "version": "0.22.0-alpha2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@gethinode/hinode",
-      "version": "0.22.0-alpha",
+      "version": "0.22.0-alpha2",
       "license": "MIT",
       "devDependencies": {
         "@fullhuman/postcss-purgecss": "^5.0.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethinode/hinode",
-  "version": "0.22.0-alpha",
+  "version": "0.22.0-alpha2",
   "description": "Hinode is a clean documentation and blog theme for Hugo, an open-source static site generator",
   "keywords": [
     "hugo",