001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.console.widgets;
018
019/**
020 * A declared calendar event category — a legend entry and the color family its events paint with.
021 *
022 * <p>
023 * The color is a fixed token family ({@link CategoryColor}), never an author-supplied inline color, so the emitted
024 * markup only ever carries a {@code jc-cal-cat--{blue|green|amber|red|neutral}} class built from the
025 * <b>sanitized</b> id/color &mdash; no CSS-value injection surface.  Legend text and tooltip are painted with
026 * {@code textContent}.
027 *
028 * @since 10.0.0
029 */
030@SuppressWarnings({
031   "java:S1845" // Fluent-builder setters intentionally mirror field names (Juneau DSL convention).
032})
033public class EventCategory {
034
035   /** Stable, unique id; charset {@code [A-Za-z][A-Za-z0-9_-]*}; drives the color class. */
036   public String id;
037
038   /** Legend text; painted with {@code textContent}. */
039   public String label;
040
041   /** Fixed token family; defaults to {@link CategoryColor#NEUTRAL}. */
042   public CategoryColor color;
043
044   /** Optional legend tooltip; painted with {@code textContent}. */
045   public String description;
046
047   /**
048    * Creates an empty category.
049    *
050    * @return A new {@link EventCategory}.
051    */
052   public static EventCategory create() {
053      return new EventCategory();
054   }
055
056   /**
057    * Sets the id.
058    *
059    * @param value The id.  Must match {@code [A-Za-z][A-Za-z0-9_-]*}.
060    * @return This object.
061    */
062   public EventCategory id(String value) {
063      id = value;
064      return this;
065   }
066
067   /**
068    * Sets the legend label.
069    *
070    * @param value The label.  Must not be <jk>null</jk> or blank.
071    * @return This object.
072    */
073   public EventCategory label(String value) {
074      label = value;
075      return this;
076   }
077
078   /**
079    * Sets the color family.
080    *
081    * @param value The color family.
082    * @return This object.
083    */
084   public EventCategory color(CategoryColor value) {
085      color = value;
086      return this;
087   }
088
089   /**
090    * Sets the legend tooltip.
091    *
092    * @param value The tooltip.
093    * @return This object.
094    */
095   public EventCategory description(String value) {
096      description = value;
097      return this;
098   }
099
100   /**
101    * The effective color family &mdash; the declared {@link #color} or {@link CategoryColor#NEUTRAL} when unset.
102    *
103    * @return The effective color family.
104    */
105   public CategoryColor effectiveColor() {
106      return color == null ? CategoryColor.NEUTRAL : color;
107   }
108
109   /** The fixed category color families, each mapped to an existing {@code --jc-tag-*} token family. */
110   public enum CategoryColor {
111
112      /** Blue token family. */
113      BLUE,
114
115      /** Green token family. */
116      GREEN,
117
118      /** Amber token family. */
119      AMBER,
120
121      /** Red token family. */
122      RED,
123
124      /** Neutral token family (the default, and the fallback for an unknown wire category). */
125      NEUTRAL;
126
127      /** The lowercased token used in the {@code jc-cal-cat--{token}} class. */
128      public String token() {
129         return name().toLowerCase(java.util.Locale.ROOT);
130      }
131   }
132}