Rewritten TS spec

(Updated in response to Mimi's feedback, 1:16 PM Wed 2/14, and 7:31 AM & 5:11 PM Thu 2/15, and 8:47 AM & 10:15 AM Fri 2/16 ...Bryan)

Triage Status Model

Each item has a triage status that colors the NOW/LATER/DONE buttons shown in the dashboard and at the top of the detail view. The dashboard is divided into sections by triage status when sorted by the triage column; within each section, items are sub-sorted by how recently their triage status changed; an internal timestamp, "triageStatusChanged", is used to track this.

Normally, this same "button" triage status is used for sorting in the dashboard; however, because we occasionally want to pin an item in place when changing its button color, or move an item to a sort position other than what its button triage status would call for (see specifics below), a secondary "section" triage status overrides the button triage status if it's present. All items have button triageStatus (and triageStatusChanged); section triageStatus and sectionTriageStatusChanged are optional.

These attributes combine to work like this:

• When we want an item to pop to the top of the NOW section, we set its button triageStatus to NOW, and its button triageStatusChanged to the current time; because the dashboard sorts NOW items first, then by descending time within the NOW section, the new item appears at the top.
• If that item were already NOW, simply changing its button triageStatusChanged time to the current time causes it to move to the top of the section.
• Because section triage status (if present) overrides button triage status for sorting, but doesn't change button color, we can cause a LATER item to appear at the top of the NOW section while keeping its LATER button color, by setting sectionTriageStatus to NOW and sectionTriageStatusChanged to the current time; because we leave button triageStatus as LATER, the button still says LATER even at the top of the NOW section.
• The reverse of this also works: if we want to change the button color (say, from NOW to DONE) without moving the item from its current sort position, we copy button triageStatus to sectionTriageStatus, and button triageStatusChanged to sectionTriageStatusChanged, before changing the button color.

Also, we internally track whether we should automatically set triage status on the item when the user changes dates on the item (see below for details). This "doAutoTriageOnDateChange" flag defaults to "on" (enabling auto-triaging), but is updated by certain actions described below.

The button triage status attributes (triageStatus and triageStatusChanged) and the doAutoTriageOnDateChange flag are shared, only if the user chooses to "Share triage status" in the sharing dialog for a given collection. Note that if the user chooses to "share triage status", alarms must be shared as well, to avoid attribute wars (and spurious conflicts) of triage values. The section triage status attributes (sectionTriageStatus and sectionTriageStatusChanged) are never shared. (Behavior of these attributes at sharing time is described below.)

Triage Status Display

Triage status is displayed as two buttons: in the rightmost column of the dashboard, and in the markup bar in the detail view. Both these widgets are clickable, and act like buttons: they have active, rollover, and mousedown states, for each of the three status values NOW, LATER, and DONE:

• NOW is represented as green (#00cc00)
• LATER is represented as yellow (#ffcc00)
• DONE is represented as 33% gray
• All are white text with a colored background; in the dashboard, the color blocks should fill up the entire cell, leaving a 1-pixel gap between rows.
• The section headers also use swatches of these colors.

Triage status and unread-ness changes

Triage status changes fall into three categories: explicit actions by the user, implicit user actions, and internal auto-triaging. Certain sharing changes can also mark an item "unread" again.

Explicit user actions affecting triage status:

• When the user clicks on a triage widget, in either the dashboard or the detail view's markup bar.
  • Button triage status will cycle through NOW, DONE, and LATER, in that order. It won't move in the dashboard, however: if it doesn't have a section triage status, its original button triage status will be copied to section triage status to pin it in place until purging.
  • (Post-preview: If the item isn't displayed in a visible dashboard (that is, a calendar view is shown), this section triage status manipulation for pinning won't be done.)
  • Changing triage status using the widgets is considered a modification with regard to the edit/update workflow (see the stamping spec).
  • When the user changes triage status using one of the widgets, the doAutoTriageOnDateChange flag is set to "off" (keep reading for how this affects future auto-triaging).
  • (Nice to have: if the new triage status matches the status that would be calculated as described below for a change to alarm time or event start time, the doAutoTriageOnDateChange flag is set back to "on" instead of being turned "off.")
• Purging: a "Triage" button on the toolbar scans all the non-"unread" items in the displayed collection: sectionTriageStatus (on any items that have it) is discarded, causing those items to re-sort to the positions determined by the button triage status. (This would cause those items to be reordered in other collections as well, since none of the triage status attributes are per-collection.)
• Post-preview: by dragging within the dashboard if it's sorted by the triage column.
  • Dragging within the dashboard artificially manipulates the triageStatusChanged value, forcing a particular ordering within a section. Positioning an item this way applies to all collections that the item is in: Given items A, B, and C, that happen to all be in both collection X and collection Y, dragging item C between A and B in collection X will guarantee that the same ordering will appear in collection Y (though it's possible for other items not in X to be between A and B in Y; C's position relative to these items in Y is arbitrary).
  • Dragging within the dashboard counts as a modification for edit/update, and if the triage status changes as a result of the drag, the doAutoTriageOnDateChange flag is updated just like clicking the widget (as described above).

Implicit user actions affecting triage status:

• Item creation
  • Normally, a new item created by the user will have NOW button triage status, and no section triage status, causing it to appear at the top of the NOW section of the dashboard. However, if the item is created on the calendar (or by any other mechanism that causes it to start its life with an assigned start time), its button triage status will be set to DONE if the start time is in the past, or LATER otherwise; its section triage status will be NOW, causing it to appear at the top of the NOW section.
• (The rest of these changes don't happen unless the doAutoTriageOnDateChange flag is "on" for that item, and they only affect button color; the item doesn't change position until the user hits the "Triage" button.)
• Changing the user alarm time on an item, or the event start or end time on an event, or stamping an item as an event
  • If it's an event:
    • LATER if the start date is in the future or if there's an alarm in the future
    • else DONE if the end date is in the past.
    • else NOW otherwise.
    • (Note that items newly stamped as events are "anytime today", and will thus be NOW.)
  • Otherwise, if the item has an alarm time in the future
    • LATER
  • Otherwise, the triage status is left alone.

Automatic operations affecting triage status:

• When a user reminder goes off, or when an event's start time is reached
  • The item's triage status gets set to NOW, and the item moves to (near) the top of the NOW section (overriding any pinning caused by sectionTriageStatus). (Its position is actually determined by the reminder or event start time that caused the move -- items will appear in reverse order that their alarms went off or times were reached. This is true even if Chandler wasn't running at the appointed times: the automatic operations will produce results in the right order when Chandler is restarted.)
  • The doAutoTriageOnDateChange flag is turned off. (Nice to have: as above, if the new triage status matches the status that would be calculated as described below for a change to alarm time or event start time, the doAutoTriageOnDateChange flag is set to "on"; otherwise, it's turned "off.")
• When items are newly received or updated via sharing or mail, if this user's "Share triage status" choice is off in all collections this item belongs to:
  • (These changes only affect item sort order, not button color; if the item had a pending unpurged sectionTriageStatus pinning it in place, this overrides it. When the next "Triage" purge happens, the item will move to the position determined by the triage status originally set by the local user.)
  • The item is moved to the top of the NOW section.
  • The item is marked "unread".
• When sharing, and any collection the item belongs to on that server has the "Share triage status" option selected
  • Button triage status (and triageStatusChanged, and doAutoTriageOnDateChange) are synced like ordinary attributes: any existing item receiving a change to button triage status will have its button color updated immediately.
  • Additionally, the item will move to the top of the NOW section (unless it already has a pending section triage status pinning it in place).
• When an error occurs syncing an item
  • The item is moved to the top of the NOW section, without changing its button color. This overrides any pending unpurged positioning pinning it in place.

The Date Column

[Note: the important date spec isn't clear - it should be this:]

The date column displays the "important date" for an item:

• if the item is an event and has both alarm and start time in the future, it's the earlier of those times.
• Otherwise, if it has one or the other of those in the future, it's that.
• Otherwise, if the item is an event and has a start time in the past, it's that.
• Otherwise, if the item has an alarm time in the past, it's that.
• Otherwise, if it's a sent or received email, it's the sent/received time.
• Otherwise, if another kind-specific date is provided, it's that (Flickr photo-taken time, RSS posting time)
• Otherwise, it's the last-modified time for the item.
• Otherwise, it's the date the item was created.